# Simple Shape Translation and Transmutation Examples

## Purpose

This document lists three dozen primary, simple showcase examples for PortaShape users to practice importing a source shape, inspecting labeled values, mapping those values, translating compatible values, transmutating structures when needed, and saving the result as a new registered shape.

These examples are intentionally smaller than the full Website Shape Translator Showcase. They should become playground fixtures, sample `.posh` bundles, guided tutorials, and UI smoke tests for the visual mapper, variable controls, transform recipes, validation panels, and shape load/save/manage dashboard.

## How to use these examples

Each example should provide:

- a source shape with a stable shape ID;
- a destination shape or template with a stable shape ID;
- a small set of labeled variables;
- one or more suggested mappings;
- at least one user-editable control;
- a preview of source, proposed, and destination values;
- a save-as-new-shape action;
- a `.posh` export containing the mapping, transform, workflow, policy, snapshot, and run evidence.

## Three dozen simple examples

| # | Example | Source shape | Destination shape | What users can try |
| --- | --- | --- | --- | --- |
| 1 | Display name formatter | `person.name_parts` | `person.display_name` | Combine first, middle, and last names into one labeled display value. |
| 2 | Split full name | `person.full_name` | `person.name_parts` | Split one name string into first, middle, last, suffix, and unresolved tokens. |
| 3 | Contact card to CRM lead | `contact.card` | `crm.lead` | Map name, email, phone, company, title, and notes into a CRM-shaped record. |
| 4 | Address label to structured address | `address.shipping_label` | `address.structured` | Parse multiline label text into street, city, region, postal code, and country. |
| 5 | Structured address to mailing label | `address.structured` | `address.shipping_label` | Compose address fields into a printable label with locale-aware formatting. |
| 6 | CSV row to profile card | `csv.customer_row` | `ui.profile_card` | Map tabular fields into visible card labels, badges, and links. |
| 7 | Profile card to CSV row | `ui.profile_card` | `csv.customer_row` | Flatten a UI component shape into exportable tabular data. |
| 8 | Blog metadata to social preview | `blog.article_meta` | `social.preview_card` | Translate title, excerpt, author, image, date, and URL into Open Graph-style preview fields. |
| 9 | Social preview to newsletter block | `social.preview_card` | `email.newsletter_block` | Transmutate preview content into an email-safe content block. |
| 10 | Product card to ecommerce item | `ui.product_card` | `commerce.product_record` | Map image, title, SKU, price, sale label, CTA, and inventory hint into product data. |
| 11 | Ecommerce item to product card | `commerce.product_record` | `ui.product_card` | Generate a reusable product card from structured product data. |
| 12 | Menu links to navigation bar | `content.link_list` | `ui.nav_bar` | Turn labeled links into ordered navigation items with active-state options. |
| 13 | Navigation bar to sitemap | `ui.nav_bar` | `site.sitemap` | Export navigational structure into a sitemap-style shape with paths and labels. |
| 14 | Task list to kanban board | `tasks.flat_list` | `workflow.kanban_board` | Group task records by status and transmutate them into columns and cards. |
| 15 | Kanban board to task list | `workflow.kanban_board` | `tasks.flat_list` | Flatten columns back into task rows while preserving status. |
| 16 | Event details to calendar entry | `event.public_details` | `calendar.entry` | Map title, date, time, location, description, and registration link into a calendar item. |
| 17 | Calendar entry to event hero | `calendar.entry` | `ui.event_hero` | Generate a page hero with date badge, headline, location, and CTA. |
| 18 | FAQ list to accordion | `content.faq_pairs` | `ui.faq_accordion` | Turn question/answer rows into accessible disclosure items. |
| 19 | Accordion to FAQ JSON | `ui.faq_accordion` | `content.faq_pairs` | Extract visible questions and answers from a component into portable content data. |
| 20 | Testimonial quotes to carousel | `content.testimonials` | `ui.carousel` | Map quotes, names, roles, images, and order into a carousel shape. |
| 21 | Carousel to static quote grid | `ui.carousel` | `ui.quote_grid` | Transmutate interactive slides into a non-interactive responsive grid. |
| 22 | Color palette to CSS variables | `design.palette` | `css.custom_properties` | Translate labeled colors into `--color-*` CSS custom properties. |
| 23 | CSS variables to design tokens | `css.custom_properties` | `design.tokens` | Infer token names, roles, scopes, and aliases from CSS variable declarations. |
| 24 | Font scale to CSS classes | `design.type_scale` | `css.utility_classes` | Generate utility classes from font sizes, line heights, and weights. |
| 25 | Pixel spacing to rem spacing | `css.pixel_spacing` | `css.rem_spacing` | Convert spacing values and show rounding, base-size, and loss metadata. |
| 26 | Theme options to user preferences | `theme.global_settings` | `user.theme_options` | Separate global defaults from personal options such as dark mode and density. |
| 27 | User preferences to app settings | `user.theme_options` | `app.settings_patch` | Promote selected personal preferences into proposed app-level settings with approval warnings. |
| 28 | Form fields to validation schema | `html.form_controls` | `schema.validation_rules` | Extract labels, names, required state, input types, min/max values, and patterns. |
| 29 | Validation schema to form UI | `schema.validation_rules` | `html.form_controls` | Generate accessible form controls from field definitions and constraints. |
| 30 | API response to table view | `api.record_collection` | `ui.data_table` | Map fields to columns, labels, sort options, filters, and row actions. |
| 31 | Table view to API query | `ui.data_table_state` | `api.query_params` | Translate table filters, sorting, pagination, and selected columns into query parameters. |
| 32 | Status enum to progress tracker | `workflow.status_enum` | `ui.progress_tracker` | Map statuses into ordered steps with labels, current-state rules, and completed styling. |
| 33 | Progress tracker to status enum | `ui.progress_tracker` | `workflow.status_enum` | Extract an enum and transition hints from visible progress steps. |
| 34 | Image metadata to gallery card | `asset.image_metadata` | `ui.gallery_card` | Map filename, alt text, dimensions, caption, credit, and tags into a gallery component. |
| 35 | Gallery card to asset manifest | `ui.gallery_card` | `asset.manifest_item` | Extract asset references and captions into a reusable manifest record. |
| 36 | Mini landing section to component shape | `html.landing_section` | `component.reusable_section` | Select a heading/body/button/image `section` or `div`, assign a shape ID, expose variables, and save it as reusable. |

## Coverage map

Together these examples exercise PortaShape's basic shape operations:

- **copy** — direct value movement, such as email to email;
- **combine** — several labeled values becoming one labeled value;
- **split** — one compound value becoming several labeled values;
- **translate** — equivalent values moving across format or context boundaries;
- **transmutate** — structure changing shape, such as a task list becoming kanban columns;
- **flatten** — nested UI or workflow structure becoming rows or records;
- **componentize** — selected markup or repeated data becoming a reusable component shape;
- **tokenize** — raw design values becoming semantic design tokens;
- **promote** — local option values becoming proposed settings with policy checks;
- **extract** — UI or file content becoming structured data;
- **generate** — structured data becoming UI, CSS, schema, or files;
- **verify** — checking loss, unresolved values, accessibility, safety, ownership, and compatibility.

## Recommended playground progression

1. Start with examples 1-5 to teach combine, split, copy, and formatting.
2. Use examples 6-13 to teach flattening, component generation, and navigation/content shape movement.
3. Use examples 14-21 to teach structural transmutation between lists, boards, accordions, grids, and carousels.
4. Use examples 22-27 to teach design tokens, CSS values, settings, options, and promotion policies.
5. Use examples 28-33 to teach forms, schemas, API/table translation, and workflow status mapping.
6. Use examples 34-36 to lead into visual selection, asset extraction, and the larger Website Shape Translator Showcase.