@pnx-mixtape/mxds 0.0.30 → 0.1.0-rc.0

package/src/Form/FormItem/__snapshots__/FormItem.stories.ts.snap

@@ -4,16 +4,18 @@ exports[`Description Before 1`] = `
 "
 <div class="mx-form-item">
     
-<label class="mx-label" for="form-item">What's your favourite music?</label>
+<label class="mx-label" for="form-item">
+  What's your favourite music?
+  </label>
 
-  <div class="mx-description" id="unique-0" role="tooltip">
+  <div class="mx-description" id="unique-0">
   Help text that provides additional information about the field.
 </div>
 
-        
+    
 <input class="mx-input__text" id="form-item" name="unique-0" type="text" value="" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0">
 
-    
+  
   
 </div>
 "
@@ -23,17 +25,19 @@ exports[`Error 1`] = `
 "
 <div class="mx-form-item">
     
-<label class="mx-label" for="form-item">What's your favourite music?</label>
+<label class="mx-label" for="form-item">
+  What's your favourite music?
+  </label>
 
   
-        
+    
 <input class="mx-input__text error" id="form-item" name="unique-0" type="text" value="Musicals" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0" aria-invalid="true">
 
-    <div class="mx-description" id="help-form-item" role="tooltip">
+  <div class="mx-description" id="help-form-item">
   Help text that provides additional information about the field.
 </div>
 
-  <div class="mx-error-message" id="status-form-item" role="tooltip">
+  <div class="mx-error-message" id="status-form-item" role="alert">
   Oops, you made a mistake.
 </div>
 
@@ -45,13 +49,15 @@ exports[`Fieldset 1`] = `
 "
 <fieldset class="mx-form-item mx-fieldset">
     
-<legend class="mx-legend">What's your favourite music?</legend>
+<legend class="mx-legend">
+  What's your favourite music?
+  </legend>
 
   
-        
+    
 <input class="mx-input__text" id="form-item" name="unique-0" type="text" value="" aria-label="Visually hidden label" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0">
 
-    <div class="mx-description" id="unique-0" role="tooltip">
+  <div class="mx-description" id="unique-0">
   Help text that provides additional information about the field.
 </div>
 
@@ -64,13 +70,15 @@ exports[`Form Item 1`] = `
 "
 <div class="mx-form-item">
     
-<label class="mx-label" for="form-item">What's your favourite music?</label>
+<label class="mx-label" for="form-item">
+  What's your favourite music?
+  </label>
 
   
-        
+    
 <input class="mx-input__text" id="form-item" name="unique-0" type="text" value="" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0">
 
-    <div class="mx-description" id="unique-0" role="tooltip">
+  <div class="mx-description" id="unique-0">
   Help text that provides additional information about the field.
 </div>
 
@@ -83,13 +91,15 @@ exports[`Required 1`] = `
 "
 <div class="mx-form-item">
     
-<label class="mx-label" for="form-item">What's your favourite music?</label>
+<label class="mx-label" for="form-item">
+  What's your favourite music?
+  </label>
 
   
-        
+    
 <input class="mx-input__text" id="form-item" name="unique-0" type="text" value="Musicals" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0" required="">
 
-    <div class="mx-description" id="unique-0" role="tooltip">
+  <div class="mx-description" id="unique-0">
   Help text that provides additional information about the field.
 </div>
 
@@ -102,17 +112,19 @@ exports[`Success 1`] = `
 "
 <div class="mx-form-item">
     
-<label class="mx-label" for="form-item">What's your favourite music?</label>
+<label class="mx-label" for="form-item">
+  What's your favourite music?
+  </label>
 
   
-        
+    
 <input class="mx-input__text success" id="form-item" name="unique-0" type="text" value="Jazz" placeholder="eg. Funk, Soul, Blues.." aria-describedby="unique-0">
 
-    <div class="mx-description" id="help-form-item" role="tooltip">
+  <div class="mx-description" id="help-form-item">
   Help text that provides additional information about the field.
 </div>
 
-  <div class="mx-success-message" id="status-form-item" role="tooltip">
+  <div class="mx-success-message" id="status-form-item" role="status">
   Congratulations, you are correct!
 </div>
 

package/src/Form/FormItem/form-item.twig

@@ -10,13 +10,7 @@
 <{{ as }}{{ attributes }}>
   {{ label }}
   {{ descriptionStart }}
-  {% if fields[0] is not empty %}
-    {% for field in fields %}
-      {{ field }}
-    {% endfor %}
-  {% else %}
-    {{ fields }}
-  {% endif %}
+  {{ fields }}
   {{ descriptionEnd }}
   {{ status }}
 </{{ as }}>

package/src/Form/Label/FormLabel.figma.ts

@@ -0,0 +1,26 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=34-57
+// source=src/Form/Label/FormLabel.tsx
+// component=FormLabel
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const label = instance.getString("Label")
+
+// `required` marks the parent FormItem as containing a required field — form.css's
+// .mx-form-item:has([required]) .mx-label::after rule only sets colour, no `content`
+// value is defined anywhere in the codebase, so the "(required)" suffix is currently a
+// dead/incomplete CSS rule. Modelled here as a visible boolean since that's clearly the
+// intent, not because the suffix actually renders in code today.
+const required = instance.getEnum("Required", { Off: false, On: true })
+
+const requiredProp = required ? " required" : ""
+
+export default {
+  example: figma.code`<FormLabel text="${label}" id="field"${requiredProp} />`,
+  imports: ['import { FormLabel } from "@pnx-mixtape/mxds/react"'],
+  id: "form-label",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Form/Label/FormLabel.tsx

@@ -5,10 +5,10 @@ type FormLabelProps = ComponentPropsWithoutRef<"label"> & {
   required?: boolean
 }
 
-const FormLabel = ({ text, id, required = false }: FormLabelProps): JSX.Element => (
+const FormLabel = ({ text, id, required }: FormLabelProps): JSX.Element => (
   <label className="mx-label" htmlFor={id}>
     {text}
-    {required && <span> (required)</span>}
+    {required && <span className="mx-required">(required)</span>}
   </label>
 )
 

package/src/Form/Label/Label.stories.ts

@@ -3,7 +3,11 @@ import Component from "./label.twig"
 import "../form.css"
 import { FormLabel as FormLabelType } from "@pnx-mixtape/ids-shape"
 
-const meta: Meta<FormLabelType> = {
+type FormLabelProps = FormLabelType & {
+  required?: boolean
+}
+
+const meta: Meta<FormLabelProps> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
@@ -13,7 +17,7 @@ const meta: Meta<FormLabelType> = {
 }
 
 export default meta
-type Story = StoryObj<FormLabelType>
+type Story = StoryObj<FormLabelProps>
 
 export const Label: Story = {}
 
@@ -23,6 +27,12 @@ export const Inline: Story = {
   },
 }
 
+export const Required: Story = {
+  args: {
+    required: true,
+  },
+}
+
 export const Legend: Story = {
   args: {
     title: "A fieldset legend",

package/src/Form/Label/__snapshots__/FormLabel.stories.tsx.snap

@@ -2,4 +2,4 @@
 
 exports[`Label 1`] = `"<label class="mx-label" for="mix-label">Label</label>"`;
 
-exports[`Required 1`] = `"<label class="mx-label" for="mix-label">Label<span> (required)</span></label>"`;
+exports[`Required 1`] = `"<label class="mx-label" for="mix-label">Label<span class="mx-required">(required)</span></label>"`;

package/src/Form/Label/__snapshots__/Label.stories.ts.snap

@@ -2,18 +2,32 @@
 
 exports[`Inline 1`] = `
 "  
-<label class="mx-label mx-label--inline" for="label">A form label</label>
+<label class="mx-label mx-label--inline" for="label">
+  A form label
+  </label>
 "
 `;
 
 exports[`Label 1`] = `
 "  
-<label class="mx-label" for="label">A form label</label>
+<label class="mx-label" for="label">
+  A form label
+  </label>
 "
 `;
 
 exports[`Legend 1`] = `
 "  
-<legend class="mx-legend" for="label">A fieldset legend</legend>
+<legend class="mx-legend" for="label">
+  A fieldset legend
+  </legend>
+"
+`;
+
+exports[`Required 1`] = `
+"  
+<label class="mx-label" for="label">
+  A form label
+  <span class="mx-required">(required)</span></label>
 "
 `;

package/src/Form/Label/label.twig

@@ -10,4 +10,7 @@
 ] %}
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
 
-<{{ as }}{{ attributes }}{% if id%} for="{{ id }}"{% endif %}>{{ title }}</{{ as }}>
+<{{ as }}{{ attributes }}{% if id%} for="{{ id }}"{% endif %}>
+  {{ title }}
+  {% if required %}<span class="mx-required">(required)</span>{% endif %}
+</{{ as }}>

package/src/Form/README.md

@@ -1,11 +1,212 @@
-# Form
+# Forms
 
-### How to use
+A cohesive form system built around the `FormItem` composition pattern. All inputs share a single CSS file and a consistent set of status states, spacing tokens, and ARIA wiring.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Form/form.cs';`
+```css
+@import "@pnx-mixtape/mxds/src/Form/form.css";
+```
 
-**JSX Components**
+---
 
-- JSX import: `import { Form, FormItem, FormText, FormLabel } from '@pnx-mixtape/mxds/src/react';`
+## The composition pattern
+
+Every form field is built from the same four layers stacked inside a `FormItem`:
+
+```
+FormItem (mx-form-item)
+├── FormLabel (mx-label)          ← visible label
+├── [input component]             ← text / select / textarea / checkbox / radio
+├── FormDescription (mx-description) ← hint text, shown by default
+└── FormDescription (mx-error-message / mx-success-message) ← status message
+```
+
+The input's `aria-describedby` is automatically wired to `help-{id}` — `FormDescription` (default status) uses the same id, so screen readers announce the hint without extra work. When a status (`INVALID` / `VALID`) is set, `FormDescription` switches its id to `status-{id}`. Combine both by setting `aria-describedby="help-{id} status-{id}"` on the input when both a description and a status block are rendered.
+
+---
+
+## HTML
+
+```html
+<div class="mx-form-item">
+  <label class="mx-label" for="email">Email address</label>
+  <input
+    class="mx-input__text error"
+    id="email"
+    type="email"
+    name="email"
+    aria-describedby="status-email"
+    aria-invalid="true"
+    required
+  />
+  <div id="status-email" class="mx-error-message">Please enter a valid email address.</div>
+</div>
+```
+
+## Input modifier classes
+
+| Class                    | Effect                                                       |
+| ------------------------ | ------------------------------------------------------------ |
+| `mx-input--wide`         | `inline-size: 100%` — fills its container                    |
+| `mx-input--small`        | Reduced border (1px), smaller chevron offset                 |
+| `mx-input--icon`         | Adds leading icon via `::before` mask                        |
+| `mx-form--inline-button` | Input + button fused into one bordered unit (used in Search) |
+
+## Form actions
+
+Wrap submit/cancel buttons in `.mx-form-actions` for consistent flex layout:
+
+```html
+<div class="mx-form-actions">
+  <button class="mx-button mx-button--dark" type="submit">Submit</button>
+  <button class="mx-button mx-button--light" type="button">Cancel</button>
+</div>
+```
+
+## Fieldset
+
+Use `.mx-fieldset` when grouping related fields under a `<legend>`:
+
+```html
+<fieldset class="mx-fieldset">
+  <legend>Contact method</legend>
+  <!-- fields -->
+</fieldset>
+```
+
+Add `.mx-fieldset--plain` or `.mx-fieldset--inline` for checkbox/radio groups (no border) or inline layout.
+
+---
+
+## React — complete field example
+
+```tsx
+import { FormItem, FormLabel, FormText, FormDescription } from "@pnx-mixtape/mxds/react"
+import { FormStatus } from "../../enums"
+
+// Valid field
+<FormItem>
+  <FormLabel id="email" text="Email address" required />
+  <FormText id="email" type="email" name="email" status={FormStatus.VALID} />
+  <FormDescription id="email" status={FormStatus.VALID}>
+    Looks good!
+  </FormDescription>
+</FormItem>
+
+// Invalid field
+<FormItem>
+  <FormLabel id="name" text="Full name" required />
+  <FormText id="name" name="name" status={FormStatus.INVALID} />
+  <FormDescription id="name" status={FormStatus.INVALID}>
+    Please enter your full name.
+  </FormDescription>
+</FormItem>
+```
+
+→ See [`FormItem/README.md`](./FormItem/README.md) for fieldset groups, inline variants, and layout options.
+
+→ See [`Checkbox/README.md`](./Checkbox/README.md) for checkbox and radio groups (these use `react-aria` and have a different pattern).
+
+---
+
+## Input components
+
+### FormText — text input
+
+```tsx
+import { FormText } from "@pnx-mixtape/mxds/react"
+;<FormText id="search" type="search" name="q" placeholder="Search…" />
+```
+
+**Props:** all native `<input>` attributes + `status?: FormStatus` (default: `DEFAULT`)
+
+Renders `mx-input__text`. Sets `aria-describedby` and `aria-invalid` automatically.
+
+### FormTextarea — multi-line text
+
+```tsx
+import { FormTextarea } from "@pnx-mixtape/mxds/react"
+;<FormTextarea id="message" name="message" />
+```
+
+**Props:** all native `<textarea>` attributes + `status?: FormStatus`
+
+Default height is 4× the standard input height.
+
+### FormSelect — dropdown
+
+```tsx
+import { FormSelect } from "@pnx-mixtape/mxds/react"
+;<FormSelect
+  id="country"
+  name="country"
+  label="Choose a country"
+  options={[
+    { label: "Australia", value: "au" },
+    { label: "New Zealand", value: "nz" },
+  ]}
+  selected="au"
+/>
+```
+
+**Props:** `options: { label, value }[]`, `label?: string` (placeholder option text), `selected?: string`, `status?: FormStatus` + all native `<select>` attributes
+
+Custom chevron via SVG mask. RTL-aware.
+
+### FormLabel — field label
+
+```tsx
+import { FormLabel } from "@pnx-mixtape/mxds/react"
+;<FormLabel id="email" text="Email address" required />
+```
+
+**Props:** `id: string` (matches input id), `text: string`, `required?: boolean` + all native `<label>` attributes
+
+Required fields append "(required)" in error colour. The `(required)` text can be overridden via the `--required-text` CSS custom property.
+
+### FormDescription — hint & status messages
+
+```tsx
+import { FormDescription } from "@pnx-mixtape/mxds/react"
+import { FormStatus } from "../../enums"
+
+<FormDescription id="email">Enter your work email address.</FormDescription>
+<FormDescription id="email" status={FormStatus.INVALID}>This field is required.</FormDescription>
+<FormDescription id="email" status={FormStatus.VALID}>Email confirmed.</FormDescription>
+```
+
+**Props:** `id: string` (renders as `help-{id}` for default, `status-{id}` for `INVALID`/`VALID`), `status?: FormStatus`
+
+| `status`  | Class                | Appearance                   |
+| --------- | -------------------- | ---------------------------- |
+| `DEFAULT` | `mx-description`     | Neutral hint text            |
+| `INVALID` | `mx-error-message`   | Red icon + error colour text |
+| `VALID`   | `mx-success-message` | Green icon + foreground text |
+
+---
+
+## Status states (`FormStatus` enum)
+
+| Value                | Class suffix | Description                                                  |
+| -------------------- | ------------ | ------------------------------------------------------------ |
+| `FormStatus.DEFAULT` | —            | Normal state                                                 |
+| `FormStatus.VALID`   | `success`    | Green border, success icon on description                    |
+| `FormStatus.INVALID` | `error`      | Red border, error icon on description, `aria-invalid="true"` |
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-form-item {
+  --required-text: " *"; /* override "(required)" label suffix */
+  --form-spacing: var(--spacing-m); /* padding inside inputs */
+  --form-element-height: 3rem; /* input height */
+  --line-width: 1px; /* input border width */
+  --line-colour: var(--colour-primary);
+  --control-size: 1.5rem; /* checkbox/radio size */
+  --placeholder-colour: var(--colour-foreground-alt);
+  --disabled-opacity: 0.5;
+}
+```

package/src/Form/Radio/FormRadio.figma.ts

@@ -0,0 +1,27 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=89-405
+// source=src/Form/Radio/FormRadio.tsx
+// component=FormRadio
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const legendHandle = instance.findText("Legend")
+const legend = legendHandle.type === "TEXT" ? legendHandle.textContent : ""
+
+const items = instance.findConnectedInstances(node => node.codeConnectId() === "radio")
+const item1 = items[0]?.executeTemplate().example
+const item2 = items[1]?.executeTemplate().example
+
+// Always renders <FormItem fieldset legend={label}> internally — FormRadio IS the
+// fieldset, not shown as a separate wrapper.
+export default {
+  example: figma.code`<FormRadio label="${legend}">
+  ${item1}
+  ${item2}
+</FormRadio>`,
+  imports: ['import { FormRadio } from "@pnx-mixtape/mxds/react"'],
+  id: "form-radio",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Form/Radio/FormRadio.tsx

@@ -9,16 +9,15 @@ const RadioContext = createContext<RadioGroupState>(null)
 
 type FormRadioProps = PropsWithChildren &
   AriaRadioGroupProps & {
-    label: string
+    label?: string
   }
 
 const FormRadio = ({ label, children, ...props }: FormRadioProps): JSX.Element => {
   const state = useRadioGroupState(props)
-  const { radioGroupProps, labelProps } = useRadioGroup(props, state)
+  const { radioGroupProps } = useRadioGroup(props, state)
 
   return (
-    <FormItem fieldset {...radioGroupProps}>
-      <legend {...labelProps}>{label}</legend>
+    <FormItem fieldset {...radioGroupProps} legend={label}>
       <RadioContext value={state}>{children}</RadioContext>
     </FormItem>
   )
@@ -41,8 +40,7 @@ const Radio = ({
   const state = use(RadioContext)
   const { inputProps } = useRadio(props, state, ref)
 
-  const classes = classNames("mx-radio", {
-    className,
+  const classes = classNames("mx-radio", className, {
     error: status === FormStatus.INVALID,
     success: status === FormStatus.VALID,
   })

package/src/Form/Radio/Radio.figma.ts

@@ -0,0 +1,29 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=89-404
+// source=src/Form/Radio/FormRadio.tsx
+// component=Radio
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const status = instance.getEnum("Status", {
+  Default: "FormStatus.DEFAULT",
+  Invalid: "FormStatus.INVALID",
+  Valid: "FormStatus.VALID",
+})
+const content = instance.getSlot("Content")
+
+const statusProp = status === "FormStatus.DEFAULT" ? "" : ` status={${status}}`
+
+// Real finding, checked against react-aria's actual types: RadioProps only has
+// `value` (required) + `isDisabled` — there is no isSelected/checked prop on an
+// individual Radio at all. Whether it renders checked is derived entirely from the
+// parent FormRadio group's own value matching this item's `value`. "Checked" here is
+// a Figma-only preview state, same context-derived-not-a-prop shape as Checkbox.
+export default {
+  example: figma.code`<Radio value="option"${statusProp}>${content}</Radio>`,
+  imports: ['import { Radio, FormStatus } from "@pnx-mixtape/mxds/react"'],
+  id: "radio",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Form/Radio/Radio.stories.ts

@@ -5,7 +5,11 @@ import Label from "../Label/label.twig"
 import "../form.css"
 import { FormItem as FormItemType } from "@pnx-mixtape/ids-shape"
 
-const meta: Meta<FormItemType> = {
+type MxFormItemType = Omit<FormItemType, "fields"> & {
+  fields?: string
+}
+
+const meta: Meta<MxFormItemType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
@@ -28,7 +32,7 @@ const meta: Meta<FormItemType> = {
         label: "No",
         value: "no",
       }),
-    ],
+    ].join(""),
   },
   parameters: {
     deepControls: { enabled: true },
@@ -47,7 +51,7 @@ const meta: Meta<FormItemType> = {
 }
 
 export default meta
-type Story = StoryObj<FormItemType>
+type Story = StoryObj<MxFormItemType>
 
 export const Radio: Story = {}
 
@@ -67,6 +71,6 @@ export const Checked: Story = {
         label: "No",
         value: "no",
       }),
-    ],
+    ].join(""),
   },
 }

package/src/Form/Radio/__snapshots__/FormRadio.stories.tsx.snap

@@ -1,3 +1,3 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Radios 1`] = `"<fieldset class="mx-form-item" role="radiogroup" aria-orientation="vertical" id="react-aria-_r_0_"><legend>Radio group</legend><div class="mx-radio"><input id="_r_6_" data-react-aria-pressable="true" tabindex="0" aria-invalid="false" type="radio" value="1" name="react-aria-_r_5_"><label for="_r_6_">Option #1</label></div><div class="mx-radio"><input id="_r_7_" data-react-aria-pressable="true" tabindex="0" aria-invalid="false" type="radio" value="2" name="react-aria-_r_5_"><label for="_r_7_">Option #2</label></div><div class="mx-radio"><input id="_r_8_" data-react-aria-pressable="true" tabindex="0" aria-invalid="false" type="radio" value="3" name="react-aria-_r_5_"><label for="_r_8_">Option #3</label></div></fieldset>"`;
+exports[`Radios 1`] = `"<fieldset class="mx-form-item mx-fieldset" role="radiogroup" aria-orientation="vertical" id="react-aria-_r_0_"><legend class="mx-legend">Radio group</legend><div class="mx-radio"><input id="_r_6_" data-react-aria-pressable="true" tabindex="0" aria-invalid="false" type="radio" value="1" name="react-aria-_r_5_"><label for="_r_6_">Option #1</label></div><div class="mx-radio"><input id="_r_8_" data-react-aria-pressable="true" tabindex="0" aria-invalid="false" type="radio" value="2" name="react-aria-_r_5_"><label for="_r_8_">Option #2</label></div><div class="mx-radio"><input id="_r_a_" data-react-aria-pressable="true" tabindex="0" aria-invalid="false" type="radio" value="3" name="react-aria-_r_5_"><label for="_r_a_">Option #3</label></div></fieldset>"`;