@canonical/pragma-cli 0.34.0 → 0.36.0

package/bundled-skills/adoption-a3-forms/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: adoption-a3-forms
+description: Migrate application forms to the Canonical form system built on react-hook-form (adoption track A3); also runs as a guided tutorial on a worked example
+---
+
+# Adoption A3 — Forms
+
+The third adoption track: move the app's forms onto the design-system form package.
+Prerequisite: track A1 (A2 recommended). Understand what this track is before starting:
+the form system is a DIFFERENT PROGRAMMING MODEL built on react-hook-form, not a restyle
+of your existing inputs.
+
+## When to Use
+
+- Track A1 is done and the app's forms should move onto the design-system form package
+- A form is being built or rewritten and should use the `Form`/`Field` model from the
+  start
+- A form contains an input type the system does not cover — the `custom` escape hatch
+  below keeps it inside the `Form` (and the gap is a finding to report)
+
+## When NOT to Use
+
+- The visual foundation is not in place yet — run `adoption-a1-styles` first
+- Swapping non-form components — that is `adoption-a2-components`
+
+## Opening move: ask, or offer the tutorial
+
+Activation is an opening, not a starting gun. Unless the first message already names
+the work, ask for the starting point — as a suggestion carrying an example, not as a
+form to fill in:
+
+> To get started, point me at the app and say which form you'd like moved first — or
+> let me find the forms and suggest a starting one.
+
+The smallest real form is usually the best first move: the programming-model switch is
+easier to see on a short one. Ask again only for what the next step genuinely blocks
+on.
+
+If the activation message already carries the starting point, do not re-ask — say what
+you took it to be, and go.
+
+Offer the tutorial in the same breath, because this track doubles as one:
+
+> Or if you'd rather see the model before touching your forms, I can run it as a
+> tutorial: I'll take a plausible example — a couple of text fields and a select — and
+> walk you through the migration on it.
+
+Tutorial mode is the step narration below, turned up: the same outcome-path-conclusion
+frame, with the reasoning behind each change made explicit. It runs on a scratch
+example, not on the person's app — nothing in their repo changes unless they ask.
+
+## Every step is narrated: outcome, path, conclusion
+
+Every step is addressed to the person — once before it runs, once when it ends. This is
+not tutorial manner. It holds in the ordinary flow too: the person is the design
+authority, and they can only steer a step they saw coming. A decision gate met cold is
+a decision they cannot really make.
+
+**Open** the step with what it is FOR — the outcome it should leave behind — and how
+you are about to get there. **Close** it with a sentence saying what it established and
+what that means for the step after. One sentence each is enough; the failure mode is
+silence, not length, and a step whose outcome looks obvious still gets its sentence
+rather than a shrug.
+
+Do:
+
+> **The first field conversion.** The outcome is one field moved onto the `Form`/`Field`
+> model, proving the wiring end to end before the rest follow. The path is to replace
+> the input with a `<Field>` and let `Form` own the state `useState` was holding.
+>
+> …
+>
+> So: the field validates and submits through react-hook-form and the local `useState`
+> is gone — every remaining field is the same move, except the file upload, which needs
+> the `custom` escape hatch.
+
+Don't:
+
+> Converted the email field. Works.
+
+Both carry the same facts. Only the first says what the step was trying to achieve and
+what it settled — and only the first lets the person cut in with the thing they know
+and the graph does not, which is the whole reason they are here.
+
+## Asked about the skill: methodology and outcomes first
+
+A question about what this skill does — what it covers, what its steps are, how it
+works — is answered in that order: the METHOD it applies and the OUTCOMES it leaves
+the person holding come first, the step-by-step breakdown comes after.
+
+Two or three sentences of method is enough: what the skill treats as its object, the
+discipline that makes it work, and what exists at the end that did not exist before.
+The enumeration then reads as steps in service of something, rather than as a list to
+be got through.
+
+What this prevents is a table of contents standing in for an answer. A reply opening
+with the step names tells someone who already knows the skill nothing new, and someone
+who does not, nothing at all.
+
+So, asked what this skill is:
+
+> It moves forms onto the design-system form package, and the thing to understand
+> before starting is that this is a DIFFERENT PROGRAMMING MODEL built on
+> react-hook-form — fields as data, `Form` owning the state — not a restyle of the
+> existing inputs. You end with forms on the `Form`/`Field` model, and anything the
+> system does not cover kept inside the `Form` through the `custom` escape hatch.
+
+Then, and only then, the breakdown.
+
+## Install + the forms styles import
+
+```bash
+bun add @canonical/react-ds-global-form @canonical/styles
+```
+
+Then BOTH stylesheets in the root stylesheet:
+
+```css
+@import url("@canonical/styles");
+@import url("@canonical/react-ds-global-form/dist/esm/index.css");
+```
+
+The first brings the global reset and tokens; the second the input chrome and field
+layout. The package builds on top of `@canonical/react-ds-global`.
+
+Forms are the heaviest consumer of the density system: control heights, field spacing,
+and baseline seating all read the `--density-*` channel, which only emits real values
+when the app root carries its context and density classes
+(`class="app comfortable"` — track A1's "Declare the surface" section). Confirm those
+classes before judging any form layout: without them the primitives silently fall back
+to app-comfortable values, and a `dense` or site-surface form renders with the wrong
+geometry.
+
+## Code standards are the gate
+
+Form migration is component code, and it falls under the live code standards — the
+`react` category at minimum, plus `testing` where the migration touches tests (take
+the actual set from the live output, not from this list). Pull them BEFORE the first
+field conversion and hold the Do/Don't pairs open while writing:
+
+```bash
+pragma standard categories                 # the live category set — never from memory
+pragma standard list --category react
+pragma standard lookup <name> --detail detailed
+```
+
+Apps follow the code standards as closely as the migration allows. Where a
+conversion has to deviate from a pulled standard, record the deviation in the PR next
+to the standard's name — and ideally file it as an issue, either to bring the app
+into line later or to propose a change to the standard itself. The standards apply
+even when the app has no pragma dependency, and they are open to contribution: a
+missing or wrong standard is something to propose a change for, not to silently work
+around.
+
+## The react-hook-form switch
+
+Form state moves INTO the form system:
+
+- `<Form onSubmit={…}>` wraps a react-hook-form `FormProvider`. Pass your own `useForm`
+  return via the `methods` prop when you need external control; otherwise `defaultValues`
+  and `mode` are enough and the Form calls `useForm` internally.
+- `Field` reads the form context via `useFormContext` — **a `Field` outside a `Form` is
+  a bug**, not a styling choice.
+- Migrating a form means DELETING its `useState`/`onChange` handler plumbing, not
+  wrapping it. If the old state code survives the migration, the migration is not done.
+
+## Fields as data
+
+Each field is a declaration, not an assembly of label + input + error markup:
+
+```tsx
+<Form onSubmit={handleSubmit}>
+  <Field name="email" inputType="email" label="Email address" description="Work address preferred" />
+</Form>
+```
+
+`inputType` is a discriminated union selecting the input subcomponent — text, textarea,
+select, checkbox, radio-style choices, date/time, phone, combobox, and more — and the
+label, description, and error wiring come with the frame.
+
+> The covered set is whatever the graph answers today. Query it live — never copy its
+> output into documentation, PRs, or this skill.
+
+Enumerate the input types that exist TODAY from the package's `Field` types and its
+Storybook stories — not from this skill.
+
+## The custom escape hatch
+
+A one-off input stays INSIDE the system:
+
+```tsx
+<Field name="tags" inputType="custom" CustomComponent={TagPicker} label="Tags" />
+```
+
+`CustomComponent` is a `React.ComponentType<InputProps>`: it keeps react-hook-form
+registration, the label/description/error framing, and validation. The escape hatch is
+for the INPUT, never for leaving the `Form`.
+
+## WIP-stage warnings
+
+Input maturity is graph data, not folklore. Before building on an input type, read its
+documentation stage — the stage lives on the block's graph entity:
+
+```bash
+pragma block list                 # find the input's row — it carries the block's IRI
+pragma graph inspect <block IRI>  # every triple, including ds:documentationStage
+```
+
+Look the row up under the PACKAGE COMPONENT's name, not the `inputType` token — the
+union maps several tokens onto one component (`"text"`, `"email"`, `"tel"` and `"url"`
+all render `TextField`/`TextInput`; `"file"` renders `FileUploadField`; `"choices"`
+renders `ChoicesField`). Read the component a token selects from the package's `Field`
+types above, then find THAT name's row.
+
+An input name can be declared at more than one tier, so the list can carry a row per
+tier — names resolve globally, not within one tier. To list every tier that declares
+the name, the name query
+`pragma graph query "SELECT ?b WHERE { ?b ds:name ?n . FILTER(LCASE(?n) = LCASE('<Name>')) }"`
+prints every tier's IRI. Inspect the one whose tier matches the package you
+installed — `global` for `@canonical/react-ds-global-form`'s inputs; the stage
+below is per-block, so another tier's row answers about a different block.
+
+Read whatever `ds:documentationStage` tag comes back — the tag vocabulary is the
+graph's, not this skill's, so do not expect a fixed value list; if the predicate is
+absent, no stage is recorded for that block. The tag's MEANING is graph data too —
+inspect the tag entity itself:
+
+```bash
+pragma graph inspect ds:tag.<name>   # the tag the stage read returned; ds:whenToApply says what it means
+```
+
+Split the action on what `ds:whenToApply` says. A tag meaning the block was rejected
+or triaged out, or that it is only PROPOSED or postponed — not yet accepted into the
+system: do NOT build on that input — raise it as a gap (the `custom` escape hatch
+covers the form meanwhile). A tag meaning the documentation is unfinished: the block
+may change under you — SAY SO in the migration PR rather than discovering it in
+production. A tag whose `ds:whenToApply` comes back blank: the stage's meaning is
+unrecorded — treat it as unknown, and say so in the PR.
+
+Debug aid: `@canonical/storybook-addon-form-state` adds a Storybook panel showing the
+live react-hook-form state while you exercise a story.
+
+## Verify
+
+- [ ] Root context and density classes present (track A1) — field spacing and control
+      seating read the `--density-*` channel.
+- [ ] Submit round-trip works, with validation errors surfaced per field.
+- [ ] The whole form is completable keyboard-only.
+- [ ] Zero dev-console warnings from the form components.
+
+## Support
+
+If this skill leads somewhere broken — a command that errors, guidance that
+contradicts what the live system answers, a gap the flow cannot cover — you are not
+stuck:
+
+- Raise an issue in the pragma repo: https://github.com/canonical/pragma/issues —
+  include the skill name, what was run, and expected vs. actual outcome.
+- Or contact the design-system team owners directly through your organization's
+  professional messaging channels for assistance.

package/bundled-skills/anatomy-author/ANATOMY_DSL_SPEC.md

@@ -0,0 +1,406 @@
+# Anatomy DSL Specification
+
+This specification presents a DSL to represent design system anatomies, providing an accurate platform-agnostic markup primitive to precede implementation.
+
+## Rationale
+
+Design systems need a formal way to describe component structure that:
+- Precedes and guides implementation
+- Is platform-agnostic (works for React, SwiftUI, Flutter, etc.)
+- Supports discussion and review
+- Enables automated tooling (auditing, code generation)
+
+## Intended Usage
+
+1. **Documentation**: Implementation primitive for markup and style bindings
+2. **Specification**: Using the tree-based DSL to identify entities to implement and/or reuse
+3. **Discussion**: Using the DSL to discuss across conversations related to DS (e.g., "I believe these nodes should be siblings, not parents of one another")
+4. **Inference**: Supporting automated inference to audit a codebase against its specifications or to support code generation
+
+## Requirements
+
+### General DSL Requirements
+
+- The DSL MUST optimize for readability
+- The DSL MUST be easy to get started with and use a familiar language
+- The scope of the DSL MUST be minimized to cover only the strict necessary - additional specification information being covered in the schema
+
+### Modelling Requirements
+
+- The children of a node MUST be modelled through a reified relation for annotation purposes
+- The DSL MUST support anonymous nodes (nodes that are not named components, for instance an unnamed "div"). In this case, the DSL should support role annotations
+- The DSL MUST support reified annotations of cardinality
+- The DSL MUST support all classes of UI Blocks identified in the ontology (Layout, Pattern, Component, Subcomponent, Group)
+
+## Type System
+
+We structure the children one-to-many relation following inspiration by [the Relay connection pattern](https://relay.dev/graphql/connections.htm) and propose the following typings.
+
+```typescript
+/* Reusable types */
+
+/**
+ * Styles use a CTI (Category-Type-Item) inspired flat key structure for
+ * platform-agnostic UI properties. This allows to avoid using language
+ * specific keys such as CSS.
+ *
+ * KEY NAMING CONVENTION:
+ * Properties follow a dot-notation pattern: "category.type[.item]"
+ * - Category: Primary concern (layout, spacing, appearance, typography, size, etc.)
+ * - Type: Specific aspect within that category
+ * - Item: Optional further specification
+ *
+ * INVARIANT VS THEMEABLE:
+ * Whether a property is invariant (structural) or themeable depends on its
+ * semantic meaning and value type, rather than strict rules:
+ *
+ * Typically invariant (structural decisions):
+ * - layout.type: "stack" | "flow" | "grid"  // Component structure
+ * - layout.direction: "horizontal" | "vertical"
+ * - size.width: "fill" | "hug" | "100%"  // Structural sizing
+ *
+ * Typically themeable (brand/theme variations):
+ * - appearance.*: Color, shadow, radius values via tokens
+ * - spacing.*: When referencing design tokens
+ * - typography.*: Font properties via tokens
+ *
+ * Context-dependent:
+ * - size.width: "320px" or "size/card/width"  // Token = themeable
+ * - size.width: "fill" or "100%"  // Structural = invariant
+ * - spacing.internal: "16"  // Fixed value = invariant
+ * - spacing.internal: "spacing/medium"  // Token = themeable
+ *
+ * The distinction is semantic: does this property define structure or appearance?
+ */
+type Styles = Record<string, TokenPath | TokenPath[] | PrimitiveValue>;
+
+/**
+ * TokenPath represents a forward-slash delimited path to a design token.
+ * Follows design token naming conventions referenced by the W3C Design Token Format.
+ *
+ * Examples:
+ * - "spacing/medium"
+ * - "color/surface/primary"
+ * - "font/size/heading/1"
+ * - "border/width/thin"
+ * - "shadow/elevated/medium"
+ * - "radius/button/default"
+ *
+ * Token paths are resolved at runtime against the active theme.
+ */
+type TokenPath = string;
+
+/**
+ * PrimitiveValue represents direct values not resolved from tokens.
+ * Used for structural decisions and fixed values.
+ *
+ * Examples:
+ * - string: "stack", "flow", "center", "fill", "100%", "1fr"
+ * - number: 1.5 (aspect ratio), 2 (column count), -1 (z-index)
+ * - boolean: true/false (for wrap, reverse, etc.)
+ */
+type PrimitiveValue = string | number | boolean;
+
+/* Main types */
+
+interface Relation {
+  /**
+   * Cardinality represents the number of allowed instances of the related node.
+   * See https://en.wikipedia.org/wiki/Cardinality_(data_modeling) for reference.
+   *
+   * Examples:
+   * - "1"     : Exactly one (required)
+   * - "0..1"  : Zero or one (optional)
+   * - "0..*"  : Zero or more
+   * - "1..*"  : One or more
+   * - "2..5"  : Between 2 and 5
+   */
+  cardinality: string;
+
+  /**
+   * Maps content to a specific slot in the parent component.
+   *
+   * Common values:
+   * - "default" : Main content (React children)
+   * - "header"  : Header slot
+   * - "footer"  : Footer slot
+   * - "icon"    : Icon placement
+   * - "label"   : Text label
+   * - Custom slots as needed
+   */
+  slotName?: string;
+}
+
+/**
+ * Base interface for all nodes in the anatomy tree.
+ */
+interface BaseNode {
+  /**
+   * Style properties using CTI-inspired keys.
+   *
+   * Common patterns and their platform mappings:
+   *
+   * LAYOUT:
+   * - "layout.type": "stack" | "flow" | "grid"
+   *   -> CSS: display + flexDirection | SwiftUI: VStack/HStack | Flutter: Column/Row
+   * - "layout.align": "center" | "start" | "end"
+   *   -> CSS: align-items | SwiftUI: alignment | Flutter: crossAxisAlignment
+   *
+   * SPACING:
+   * - "spacing.internal": "spacing/medium"
+   *   -> CSS: padding | SwiftUI: .padding() | Flutter: EdgeInsets
+   * - "spacing.external": "spacing/large"
+   *   -> CSS: margin | SwiftUI: frame modifiers | Flutter: Container margin
+   * - "spacing.gap": "spacing/small"
+   *   -> CSS: gap | SwiftUI: spacing parameter | Flutter: SizedBox between
+   *
+   * APPEARANCE:
+   * - "appearance.background": "color/surface/primary"
+   *   -> CSS: background | SwiftUI: .background() | Flutter: Container color
+   * - "appearance.radius": "radius/medium"
+   *   -> CSS: border-radius | SwiftUI: .cornerRadius() | Flutter: BorderRadius
+   *
+   * SIZE:
+   * - "size.width": "fill" | "hug" | "size/card/width"
+   *   -> CSS: width: 100% | auto | var() | SwiftUI: .frame() | Flutter: constraints
+   *
+   * Examples showing invariant vs themeable:
+   * {
+   *   "layout.type": "grid",                    // Invariant: structural
+   *   "layout.columns": "1fr 300px 1fr",        // Invariant: grid structure
+   *   "spacing.gap": "spacing/grid/gap",        // Themeable: token reference
+   *   "appearance.background": "color/surface", // Themeable: always
+   *   "size.width": "fill",                     // Invariant: structural behavior
+   *   "size.max.width": "size/container/max",   // Themeable: token reference
+   *   "typography.align": "center",             // Invariant: structural
+   *   "typography.size": "font/size/body",      // Themeable: token reference
+   * }
+   */
+  styles?: Styles;
+
+  /**
+   * Child nodes and their relationships.
+   * Enables recursive component composition.
+   */
+  edges?: Edge[];
+}
+
+/**
+ * Named nodes represent identifiable components in the design system.
+ */
+interface NamedNode extends BaseNode {
+  /**
+   * Unique identifier following "tier.type.name" pattern.
+   * Maps to URI field on UI Block in the ontology.
+   *
+   * Examples:
+   * - "global.component.button"
+   * - "global.component.card"
+   * - "apps.layout.application_layout"
+   */
+  uri: string;
+}
+
+/**
+ * Anonymous nodes represent structural elements without DS identity.
+ */
+interface AnonymousNode extends BaseNode {
+  /**
+   * Human-readable description of the node's purpose.
+   *
+   * Examples:
+   * - "content wrapper"
+   * - "spacer element"
+   * - "icon container"
+   * - "layout grid cell"
+   */
+  role: string;
+}
+
+/**
+ * Union type for all possible nodes.
+ */
+type Node = NamedNode | AnonymousNode;
+
+/**
+ * A switch fills one position with ONE of several alternatives,
+ * making polymorphism explicit at the edge level.
+ * The discriminator says who chooses:
+ * - "props"    : the consumer chooses via component props
+ * - "internal" : the component chooses from its own state
+ * - "override" : the consumer may replace the default with a custom component
+ */
+interface Switch {
+  on: "props" | "internal" | "override";
+  cases: SwitchCase[];
+}
+
+/**
+ * One switch alternative — exactly one of `uri` or `node`.
+ * `uri` is the shorthand for `node: { uri }`; use the full `node` form
+ * when the case carries styles or edges. The reserved URI `$custom`
+ * marks a case filled by a user-provided component.
+ */
+interface SwitchCase {
+  uri?: string;
+  node?: Node;
+
+  /** Marks the default case. */
+  default?: boolean;
+}
+
+/**
+ * Represents a parent-child relationship in the anatomy tree.
+ */
+interface Edge {
+  /** The child node (Named or Anonymous) — exactly one of `node` or `switch` */
+  node?: Node;
+
+  /** A polymorphic position (mutually exclusive with node) */
+  switch?: Switch;
+
+  /** Relationship metadata (cardinality, slot) */
+  relation: Relation;
+}
+
+/**
+ * Root specification for a component anatomy.
+ * The top-level node must always be Named.
+ */
+interface AnatomySpec {
+  node: NamedNode;
+}
+```
+
+## Language Choice
+
+We propose the use of YAML, a mature indentation-based configuration syntax based on scalars, maps and lists. The main contender we have considered aside from YAML was JSON, rejected for its verbosity. We have also rejected TOML (maps with difficulty deeply nested nodes), SDLang and KDL (promising markup syntaxes without wide adoption at present).
+
+## Examples
+
+### Accordion
+
+```yaml
+node:
+  uri: global.component.accordion
+  styles:
+    # Structural (implicitly invariant)
+    layout.type: stack
+    layout.direction: vertical
+
+    # Themeable
+    appearance.border: border/style/accordion
+
+  edges:
+    # The repeating child is NAMED — reference its URI only; its subtree
+    # lives in its own anatomy. The live Accordion does the same.
+    - node:
+        uri: global.subcomponent.accordion-item
+      relation:
+        cardinality: "1..*"
+        slotName: default
+```
+
+The child's own anatomy — a separate spec on `global.subcomponent.accordion-item`
+(transcribed from the live block) — carries the subtree as anonymous roles:
+
+```yaml
+node:
+  uri: global.subcomponent.accordion-item
+  styles:
+    layout.type: stack
+    layout.direction: vertical
+  edges:
+    - node:
+        role: header tab
+        styles:
+          layout.type: flow
+          layout.direction: horizontal
+          layout.align: center
+          interaction.cursor: pointer
+        edges:
+          - node:
+              role: control
+              styles:
+                size.width: size/icon/small
+                size.height: size/icon/small
+            relation:
+              cardinality: "1"
+          - node:
+              role: heading
+            relation:
+              cardinality: "1"
+              slotName: default
+      relation:
+        cardinality: "1"
+        slotName: header
+
+    - node:
+        role: content panel
+        styles:
+          layout.overflow: hidden
+      relation:
+        cardinality: "1"
+        slotName: default
+```
+
+### Card
+
+```yaml
+node:
+  uri: global.component.card
+  styles:
+    # Structural (implicitly invariant)
+    layout.type: stack
+    layout.direction: vertical
+
+    # Themeable
+    appearance.background: color/surface/card
+    appearance.shadow: shadow/card
+    appearance.radius: shape/rounded/full
+    spacing.gap: spacing/small
+
+  edges:
+    # Named children reference their URI only (each carries its own styles
+    # in its own anatomy); anonymous nodes carry their styles inline. A
+    # named child may carry contextual style overrides — never a copy of
+    # its subtree. The live Card models it the same way.
+    - node:
+        uri: global.subcomponent.card-header
+      relation:
+        cardinality: "0..1"
+        slotName: header
+
+    - node:
+        uri: global.subcomponent.card-image
+      relation:
+        cardinality: "0..1"
+        slotName: media
+
+    - node:
+        uri: global.subcomponent.card-content
+      relation:
+        cardinality: "1..1"
+        slotName: default
+
+    - node:
+        uri: global.subcomponent.card-footer
+      relation:
+        cardinality: "0..1"
+        slotName: footer
+```
+
+## Further Work
+
+The following features would require additional work to this specification:
+
+- Representation of related nodes displayed in portals
+- Representation of conditional display
+- Inheritance reference for styles (e.g., "NetworkCard" inherits the styles from "Card")
+
+## References
+
+Two main references have supported our reflection:
+
+1. The work of the [Open UI W3C Working Group](https://open-ui.org/), which takes interest in a code-based anatomy for their specifications ([Example](https://open-ui.org/components/accordion.explainer/))
+2. The work of Nathan Curtis, exploring a similar syntax in his article "[Components as Data](https://medium.com/@nathanacurtis/components-as-data-2be178777f21)"