@flood-md/agent 0.2.10 → 0.2.12

package/dist/materials/recipe-settings-workspace.md

@@ -0,0 +1,232 @@
+# Settings workspace
+
+[Open the working composition](/playground/settings).
+
+Use a settings page when a person needs to review and change several related
+preferences together. This example groups workspace details and notifications
+in one form with a single save boundary. Fieldset names the groups, Field
+associates labels and errors, and Grid lets related fields share tracks when
+there is room. Use a standalone form control for a preference that should
+apply immediately and has no shared save boundary.
+
+## Save and discard
+
+The host keeps a draft and the last accepted snapshot. Save validates the
+workspace name, focuses its input if invalid and writes the full proposal
+before announcing success. A write failure leaves the draft available for
+retry. Discard restores the accepted snapshot and moves focus back to the first
+field. Keep the save control available after success so a focused submit
+button stays in the tab order.
+
+This playground uses a dedicated browser storage key. The first visit starts
+with defaults. If a saved snapshot cannot be read or parsed, show a retry
+action and leave that snapshot intact. Use the host's actual persistence and
+permission model when adapting the recipe.
+
+## Source
+
+```tsx
+"use client";
+
+import { useEffect, useRef, useState, type FormEvent } from "react";
+import {
+  Alert, Button, Container, Field, Fieldset, Grid, Heading, Inline,
+  Input, Select, Stack, Surface, Switch, Text,
+} from "@flood-md/react";
+import "./settings-workspace.css";
+
+const storageKey = "flood:settings-workspace:v1";
+const timeZones = ["UTC", "Europe/London", "America/New_York", "Asia/Tokyo"] as const;
+const maxNameLength = 80;
+type TimeZone = typeof timeZones[number];
+
+interface WorkspaceSettings {
+  name: string;
+  timeZone: TimeZone;
+  assignmentAlerts: boolean;
+  weeklyDigest: boolean;
+}
+
+const defaults: WorkspaceSettings = {
+  name: "Studio North",
+  timeZone: "UTC",
+  assignmentAlerts: true,
+  weeklyDigest: false,
+};
+
+function isTimeZone(value: unknown): value is TimeZone {
+  return timeZones.some(timeZone => timeZone === value);
+}
+
+function readSettings(): WorkspaceSettings {
+  const snapshot = window.localStorage.getItem(storageKey);
+  if (snapshot === null) return defaults;
+  const value: unknown = JSON.parse(snapshot);
+  if (
+    typeof value === "object" && value !== null &&
+    "name" in value && typeof value.name === "string" && value.name.trim() &&
+    value.name.length <= maxNameLength &&
+    "timeZone" in value && isTimeZone(value.timeZone) &&
+    "assignmentAlerts" in value && typeof value.assignmentAlerts === "boolean" &&
+    "weeklyDigest" in value && typeof value.weeklyDigest === "boolean"
+  ) {
+    return {
+      name: value.name,
+      timeZone: value.timeZone,
+      assignmentAlerts: value.assignmentAlerts,
+      weeklyDigest: value.weeklyDigest,
+    };
+  }
+  throw new Error("Invalid workspace settings");
+}
+
+export function SettingsWorkspace() {
+  const [accepted, setAccepted] = useState<WorkspaceSettings | null>(null);
+  const [draft, setDraft] = useState(defaults);
+  const [readError, setReadError] = useState(false);
+  const [nameError, setNameError] = useState("");
+  const [saveError, setSaveError] = useState("");
+  const [notice, setNotice] = useState("");
+  const nameInput = useRef<HTMLInputElement>(null);
+
+  function load() {
+    try {
+      const settings = readSettings();
+      setAccepted(settings);
+      setDraft(settings);
+      setReadError(false);
+    } catch {
+      setReadError(true);
+    }
+  }
+
+  useEffect(load, []);
+
+  const dirty = accepted !== null && (
+    draft.name !== accepted.name || draft.timeZone !== accepted.timeZone ||
+    draft.assignmentAlerts !== accepted.assignmentAlerts || draft.weeklyDigest !== accepted.weeklyDigest
+  );
+
+  function update<K extends keyof WorkspaceSettings>(key: K, value: WorkspaceSettings[K]) {
+    setDraft(current => ({ ...current, [key]: value }));
+    setNotice("");
+    if (key === "name") setNameError("");
+  }
+
+  function save(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!accepted) return;
+    const name = draft.name.trim();
+    if (!name) {
+      setNameError("Enter a workspace name.");
+      nameInput.current?.focus();
+      return;
+    }
+    const proposal = { ...draft, name };
+    try {
+      window.localStorage.setItem(storageKey, JSON.stringify(proposal));
+    } catch {
+      setSaveError("Settings could not be saved. Try again.");
+      return;
+    }
+    setAccepted(proposal);
+    setDraft(proposal);
+    setNameError("");
+    setSaveError("");
+    setNotice("Settings saved.");
+  }
+
+  function reset() {
+    if (!accepted) return;
+    setDraft(accepted);
+    setNameError("");
+    setSaveError("");
+    setNotice("Unsaved changes discarded.");
+    nameInput.current?.focus({ preventScroll: true });
+  }
+
+  return (
+    <Container size="md" gutter="4">
+      <Stack gap="6">
+        <Heading level={1} size="page">Workspace settings</Heading>
+        {readError ? (
+          <Stack gap="4">
+            <Alert tone="error" announcement="polite">Settings could not be loaded.</Alert>
+            <Inline><Button variant="subtle" onClick={load}>Retry</Button></Inline>
+          </Stack>
+        ) : accepted ? (
+          <Surface padding="6" elevation="raised">
+            <form aria-label="Workspace settings" onSubmit={save} noValidate>
+              <Stack gap="6">
+                <Fieldset legend="General" legendSize="section">
+                  <Grid minItemWidth="14rem" gap="4">
+                    <Field label="Workspace name" required error={nameError}>
+                      {props => (
+                        <Input {...props} ref={nameInput} name="name" maxLength={maxNameLength}
+                          value={draft.name} onChange={event => update("name", event.currentTarget.value)} />
+                      )}
+                    </Field>
+                    <Field label="Time zone">
+                      {props => (
+                        <Select {...props} name="timeZone" value={draft.timeZone}
+                          onChange={event => {
+                            const value = event.currentTarget.value;
+                            if (isTimeZone(value)) update("timeZone", value);
+                          }}>
+                          {timeZones.map(timeZone => <option key={timeZone}>{timeZone}</option>)}
+                        </Select>
+                      )}
+                    </Field>
+                  </Grid>
+                </Fieldset>
+                <Fieldset legend="Notifications" legendSize="section">
+                  <Stack gap="0" className="settings-switches">
+                    <Switch className="settings-switch" label="New assignments" name="assignmentAlerts" checked={draft.assignmentAlerts}
+                      onChange={event => update("assignmentAlerts", event.currentTarget.checked)} />
+                    <Switch className="settings-switch" label="Weekly summary" name="weeklyDigest" checked={draft.weeklyDigest}
+                      onChange={event => update("weeklyDigest", event.currentTarget.checked)} />
+                  </Stack>
+                </Fieldset>
+                <Stack gap="4">
+                  {saveError && <Alert tone="error" announcement="polite">{saveError}</Alert>}
+                  <Inline gap="3">
+                    <Button type="submit">Save settings</Button>
+                    <Button variant="subtle" disabled={!dirty} onClick={reset}>Discard changes</Button>
+                    <Text size="compact" tone="subtle" role="status">{notice}</Text>
+                  </Inline>
+                </Stack>
+              </Stack>
+            </form>
+          </Surface>
+        ) : <Text role="status">Loading settings…</Text>}
+      </Stack>
+    </Container>
+  );
+}
+```
+
+```css
+.settings-switches {
+  max-inline-size: 16rem;
+}
+
+.flood-root .settings-switch {
+  inline-size: 100%;
+  justify-content: space-between;
+}
+
+.settings-switch input {
+  flex: none;
+}
+```
+
+## Review
+
+Check empty-name validation and its focus target, changes across sections,
+discard, persistence after reload and read/write failure. Confirm the form
+stacks at narrow widths and the labels remain readable with enlarged text.
+
+Compare the legend with the first switch label, then compare the spacing
+between the two switch labels. The row target already creates pitch. Align
+the tracks at the end of a bounded column and verify that each label still
+pairs clearly with its switch. See [visible weight](../layout.md#review-visible-weight).

package/dist/materials/token-sys.color.context.base.action-disabled.json

@@ -0,0 +1,41 @@
+{
+  "role": "sys.color.context.base.action-disabled",
+  "cssName": "--flood-sys-color-context-base-action-disabled",
+  "description": "Canvas-context action-disabled; explicit reset for a nested canvas scope",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.color.context.base.action-disabled",
+      "type": "color",
+      "cssName": "--flood-sys-color-context-base-action-disabled",
+      "description": "Canvas-context action-disabled; explicit reset for a nested canvas scope",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.11",
+      "usage": {
+        "allowed": [
+          "Canvas-context action-disabled; explicit reset for a nested canvas scope"
+        ],
+        "avoid": [
+          "Replacing focus, text or semantic feedback colors"
+        ]
+      },
+      "value": {
+        "colorSpace": "srgb",
+        "components": [
+          0.12941176470588237,
+          0.12941176470588237,
+          0.12941176470588237
+        ],
+        "alpha": 1
+      },
+      "alias": "ref.color.neutral.900",
+      "dependencies": [
+        "ref.color.neutral.900"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.color.context.base.action-hover.json

@@ -0,0 +1,41 @@
+{
+  "role": "sys.color.context.base.action-hover",
+  "cssName": "--flood-sys-color-context-base-action-hover",
+  "description": "Canvas-context action-hover; explicit reset for a nested canvas scope",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.color.context.base.action-hover",
+      "type": "color",
+      "cssName": "--flood-sys-color-context-base-action-hover",
+      "description": "Canvas-context action-hover; explicit reset for a nested canvas scope",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.11",
+      "usage": {
+        "allowed": [
+          "Canvas-context action-hover; explicit reset for a nested canvas scope"
+        ],
+        "avoid": [
+          "Replacing focus, text or semantic feedback colors"
+        ]
+      },
+      "value": {
+        "colorSpace": "srgb",
+        "components": [
+          0.1568627450980392,
+          0.1568627450980392,
+          0.1568627450980392
+        ],
+        "alpha": 1
+      },
+      "alias": "ref.color.neutral.850",
+      "dependencies": [
+        "ref.color.neutral.850"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.color.context.base.action-pressed.json

@@ -0,0 +1,41 @@
+{
+  "role": "sys.color.context.base.action-pressed",
+  "cssName": "--flood-sys-color-context-base-action-pressed",
+  "description": "Canvas-context action-pressed; explicit reset for a nested canvas scope",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.color.context.base.action-pressed",
+      "type": "color",
+      "cssName": "--flood-sys-color-context-base-action-pressed",
+      "description": "Canvas-context action-pressed; explicit reset for a nested canvas scope",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.11",
+      "usage": {
+        "allowed": [
+          "Canvas-context action-pressed; explicit reset for a nested canvas scope"
+        ],
+        "avoid": [
+          "Replacing focus, text or semantic feedback colors"
+        ]
+      },
+      "value": {
+        "colorSpace": "srgb",
+        "components": [
+          0.18823529411764706,
+          0.18823529411764706,
+          0.18823529411764706
+        ],
+        "alpha": 1
+      },
+      "alias": "ref.color.neutral.800",
+      "dependencies": [
+        "ref.color.neutral.800"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.color.context.base.action-rest.json

@@ -0,0 +1,41 @@
+{
+  "role": "sys.color.context.base.action-rest",
+  "cssName": "--flood-sys-color-context-base-action-rest",
+  "description": "Canvas-context action-rest; explicit reset for a nested canvas scope",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.color.context.base.action-rest",
+      "type": "color",
+      "cssName": "--flood-sys-color-context-base-action-rest",
+      "description": "Canvas-context action-rest; explicit reset for a nested canvas scope",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.11",
+      "usage": {
+        "allowed": [
+          "Canvas-context action-rest; explicit reset for a nested canvas scope"
+        ],
+        "avoid": [
+          "Replacing focus, text or semantic feedback colors"
+        ]
+      },
+      "value": {
+        "colorSpace": "srgb",
+        "components": [
+          0.12941176470588237,
+          0.12941176470588237,
+          0.12941176470588237
+        ],
+        "alpha": 1
+      },
+      "alias": "ref.color.neutral.900",
+      "dependencies": [
+        "ref.color.neutral.900"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.color.context.base.avatar-background.json

@@ -0,0 +1,41 @@
+{
+  "role": "sys.color.context.base.avatar-background",
+  "cssName": "--flood-sys-color-context-base-avatar-background",
+  "description": "Canvas avatar-background",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.color.context.base.avatar-background",
+      "type": "color",
+      "cssName": "--flood-sys-color-context-base-avatar-background",
+      "description": "Canvas avatar-background",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.11",
+      "usage": {
+        "allowed": [
+          "Canvas avatar-background"
+        ],
+        "avoid": [
+          "Replacing focus, text or semantic feedback colors"
+        ]
+      },
+      "value": {
+        "colorSpace": "srgb",
+        "components": [
+          0.18823529411764706,
+          0.18823529411764706,
+          0.18823529411764706
+        ],
+        "alpha": 1
+      },
+      "alias": "ref.color.neutral.800",
+      "dependencies": [
+        "ref.color.neutral.800"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.color.context.base.border-decorative.json

@@ -0,0 +1,41 @@
+{
+  "role": "sys.color.context.base.border-decorative",
+  "cssName": "--flood-sys-color-context-base-border-decorative",
+  "description": "Canvas-context border-decorative; explicit reset for a nested canvas scope",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.color.context.base.border-decorative",
+      "type": "color",
+      "cssName": "--flood-sys-color-context-base-border-decorative",
+      "description": "Canvas-context border-decorative; explicit reset for a nested canvas scope",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.11",
+      "usage": {
+        "allowed": [
+          "Canvas-context border-decorative; explicit reset for a nested canvas scope"
+        ],
+        "avoid": [
+          "Replacing focus, text or semantic feedback colors"
+        ]
+      },
+      "value": {
+        "colorSpace": "srgb",
+        "components": [
+          0.2196078431372549,
+          0.2196078431372549,
+          0.2196078431372549
+        ],
+        "alpha": 1
+      },
+      "alias": "ref.color.neutral.750",
+      "dependencies": [
+        "ref.color.neutral.750"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.color.context.base.divider-decorative.json

@@ -0,0 +1,41 @@
+{
+  "role": "sys.color.context.base.divider-decorative",
+  "cssName": "--flood-sys-color-context-base-divider-decorative",
+  "description": "Canvas-context divider-decorative; explicit reset for a nested canvas scope",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.color.context.base.divider-decorative",
+      "type": "color",
+      "cssName": "--flood-sys-color-context-base-divider-decorative",
+      "description": "Canvas-context divider-decorative; explicit reset for a nested canvas scope",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.11",
+      "usage": {
+        "allowed": [
+          "Canvas-context divider-decorative; explicit reset for a nested canvas scope"
+        ],
+        "avoid": [
+          "Replacing focus, text or semantic feedback colors"
+        ]
+      },
+      "value": {
+        "colorSpace": "srgb",
+        "components": [
+          0.2196078431372549,
+          0.2196078431372549,
+          0.2196078431372549
+        ],
+        "alpha": 1
+      },
+      "alias": "ref.color.neutral.750",
+      "dependencies": [
+        "ref.color.neutral.750"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.color.context.base.field-background.json

@@ -0,0 +1,41 @@
+{
+  "role": "sys.color.context.base.field-background",
+  "cssName": "--flood-sys-color-context-base-field-background",
+  "description": "Canvas-context field-background; explicit reset for a nested canvas scope",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.color.context.base.field-background",
+      "type": "color",
+      "cssName": "--flood-sys-color-context-base-field-background",
+      "description": "Canvas-context field-background; explicit reset for a nested canvas scope",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.11",
+      "usage": {
+        "allowed": [
+          "Canvas-context field-background; explicit reset for a nested canvas scope"
+        ],
+        "avoid": [
+          "Replacing focus, text or semantic feedback colors"
+        ]
+      },
+      "value": {
+        "colorSpace": "srgb",
+        "components": [
+          0.1568627450980392,
+          0.1568627450980392,
+          0.1568627450980392
+        ],
+        "alpha": 1
+      },
+      "alias": "ref.color.neutral.850",
+      "dependencies": [
+        "ref.color.neutral.850"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.color.context.base.field-border.json

@@ -0,0 +1,41 @@
+{
+  "role": "sys.color.context.base.field-border",
+  "cssName": "--flood-sys-color-context-base-field-border",
+  "description": "Canvas-context field-border; explicit reset for a nested canvas scope",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.color.context.base.field-border",
+      "type": "color",
+      "cssName": "--flood-sys-color-context-base-field-border",
+      "description": "Canvas-context field-border; explicit reset for a nested canvas scope",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.11",
+      "usage": {
+        "allowed": [
+          "Canvas-context field-border; explicit reset for a nested canvas scope"
+        ],
+        "avoid": [
+          "Replacing focus, text or semantic feedback colors"
+        ]
+      },
+      "value": {
+        "colorSpace": "srgb",
+        "components": [
+          0.2196078431372549,
+          0.2196078431372549,
+          0.2196078431372549
+        ],
+        "alpha": 1
+      },
+      "alias": "ref.color.neutral.750",
+      "dependencies": [
+        "ref.color.neutral.750"
+      ],
+      "dependents": []
+    }
+  ]
+}

package/dist/materials/token-sys.color.context.base.field-disabled.json

@@ -0,0 +1,41 @@
+{
+  "role": "sys.color.context.base.field-disabled",
+  "cssName": "--flood-sys-color-context-base-field-disabled",
+  "description": "Canvas-context field-disabled; explicit reset for a nested canvas scope",
+  "contexts": [
+    {
+      "preset": "neutral",
+      "theme": "dark",
+      "id": "sys.color.context.base.field-disabled",
+      "type": "color",
+      "cssName": "--flood-sys-color-context-base-field-disabled",
+      "description": "Canvas-context field-disabled; explicit reset for a nested canvas scope",
+      "status": "experimental",
+      "visibility": "public",
+      "owner": "foundations",
+      "since": "0.2.11",
+      "usage": {
+        "allowed": [
+          "Canvas-context field-disabled; explicit reset for a nested canvas scope"
+        ],
+        "avoid": [
+          "Replacing focus, text or semantic feedback colors"
+        ]
+      },
+      "value": {
+        "colorSpace": "srgb",
+        "components": [
+          0.12941176470588237,
+          0.12941176470588237,
+          0.12941176470588237
+        ],
+        "alpha": 1
+      },
+      "alias": "ref.color.neutral.900",
+      "dependencies": [
+        "ref.color.neutral.900"
+      ],
+      "dependents": []
+    }
+  ]
+}