@loworbitstudio/visor 1.27.0 → 1.28.0

package/dist/visor-manifest.json

@@ -1,6 +1,6 @@
 {
   "version": "0.4.0",
-  "generated_at": "2026-09-23T03:16:40.729Z",
+  "generated_at": "2026-09-24T03:45:50.617Z",
   "components": {
     "accessibility-specimen": {
       "category": "specimen",
@@ -1034,7 +1034,8 @@
           "sm",
           "md",
           "lg",
-          "dlg"
+          "dlg",
+          "icon"
         ]
       },
       "props": [
@@ -1045,9 +1046,9 @@
         },
         {
           "name": "size",
-          "type": "'sm' | 'md' | 'lg' | 'dlg'",
+          "type": "'sm' | 'md' | 'lg' | 'dlg' | 'icon'",
           "default": "md",
-          "description": "Standard sizes plus `dlg` — the compact dialog-footer button (dlg-btn) from the Animal dialog substrate (VI-620): 11px/600 text, tokenized ~8/12px padding, radius-lg. Its three intents reuse the variant axis — primary via variant=\"default\", ghost via variant=\"ghost\" (renders a hairline-outlined, secondary-ink face at dlg size), danger via variant=\"destructive\" (renders a subtle-danger face at dlg size).\n"
+          "description": "Standard sizes plus `dlg` — the compact dialog-footer button (dlg-btn) from the Animal dialog substrate (VI-620): 11px/600 text, tokenized ~8/12px padding, radius-lg. Its three intents reuse the variant axis — primary via variant=\"default\", ghost via variant=\"ghost\" (renders a hairline-outlined, secondary-ink face at dlg size), danger via variant=\"destructive\" (renders a subtle-danger face at dlg size). `icon` is a square icon-only mark — glyph (--button-icon-size) plus a hit-target pad (--button-icon-pad) on every side, so width always equals height. Use it with variant=\"ghost\" for a bare mark in secondary ink. Requires an aria-label; warns in development without one.\n"
         },
         {
           "name": "asChild",
@@ -1105,6 +1106,32 @@
         "--border-default",
         "--border-focus",
         "--border-strong",
+        "--button-dlg-font-size",
+        "--button-dlg-letter-spacing",
+        "--button-dlg-radius",
+        "--button-dlg-text-transform",
+        "--button-icon-ghost-color",
+        "--button-icon-pad",
+        "--button-icon-radius",
+        "--button-icon-size",
+        "--button-letter-spacing",
+        "--button-lg-font-size",
+        "--button-lg-letter-spacing",
+        "--button-lg-radius",
+        "--button-lg-text-transform",
+        "--button-md-font-size",
+        "--button-md-letter-spacing",
+        "--button-md-radius",
+        "--button-md-text-transform",
+        "--button-radius",
+        "--button-sm-font-size",
+        "--button-sm-letter-spacing",
+        "--button-sm-radius",
+        "--button-sm-text-transform",
+        "--button-text-transform",
+        "--control-edge-color",
+        "--control-edge-style",
+        "--control-edge-width",
         "--destructive",
         "--focus-ring-offset",
         "--focus-ring-width",
@@ -1586,8 +1613,13 @@
         "--checkbox-bg-checked",
         "--checkbox-border",
         "--checkbox-border-checked",
+        "--checkbox-edgeless-bg",
         "--checkbox-radius",
         "--checkbox-size",
+        "--control-edge-color",
+        "--control-edge-style",
+        "--control-edge-width",
+        "--control-state-edge-width",
         "--focus-ring-width",
         "--hairline-strong",
         "--interactive-primary-bg",
@@ -1767,6 +1799,9 @@
         "--chip-sm-padding-x",
         "--chip-text-color",
         "--chip-text-transform",
+        "--control-edge-color",
+        "--control-edge-style",
+        "--control-edge-width",
         "--focus-ring-offset",
         "--focus-ring-width",
         "--font-body",
@@ -4100,6 +4135,10 @@
       ],
       "tokens_used": [
         "--border-default",
+        "--control-drop-edge-style",
+        "--control-drop-edge-width",
+        "--control-edge-color",
+        "--control-edge-width",
         "--empty-state-actions-gap",
         "--empty-state-bg",
         "--empty-state-border",
@@ -4384,6 +4423,10 @@
         "class-variance-authority"
       ],
       "tokens_used": [
+        "--field-label-color",
+        "--field-label-font-size",
+        "--field-label-letter-spacing",
+        "--field-label-text-transform",
         "--font-size-sm",
         "--font-size-xs",
         "--font-weight-medium",
@@ -4503,6 +4546,10 @@
         "--border-default",
         "--border-focus",
         "--border-strong",
+        "--control-drop-edge-style",
+        "--control-drop-edge-width",
+        "--control-edge-color",
+        "--control-edge-width",
         "--focus-ring-offset",
         "--focus-ring-width",
         "--font-size-sm",
@@ -5307,6 +5354,93 @@
       ],
       "example": "<Inline gap=\"sm\">\n  <Button>Save</Button>\n  <Button variant=\"secondary\">Cancel</Button>\n</Inline>\n\n<Inline gap=\"xs\" wrap>\n  {tags.map(t => <Badge key={t}>{t}</Badge>)}\n</Inline>\n"
     },
+    "inline-edit": {
+      "category": "form",
+      "description": "Inline-editable text — the text, then a pencil. A click or Enter turns it into an input in place, at the same size; Enter, blur or Tab commits, Escape restores, and clearing it brings back a muted default.",
+      "when_to_use": [
+        "A title the user can rename where it stands — a section heading, a photo set's name, a venue group, a rider's title",
+        "A single-line value whose default should come back when the user clears it",
+        "Renaming at the size of the heading being renamed, with no layout jump into an editing state"
+      ],
+      "when_not_to_use": [
+        "Multi-line text — use Textarea",
+        "Rich text — use a dedicated rich-text editor",
+        "A labelled card tile with a save button and an AI action — use EditableBlock",
+        "A field inside a form that is always editable — use Input with Field"
+      ],
+      "variants": {
+        "state": {
+          "rest": "The text (or the muted default), then the pencil. No edge.",
+          "editing": "A single-line input in the text's place, at the same size, drawing the shared control edge."
+        }
+      },
+      "props": [
+        {
+          "name": "value",
+          "type": "string",
+          "description": "The committed text. An empty string means no override, and `defaultValue` shows instead."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "default": "\"\"",
+          "description": "Shown, muted, while `value` is empty, and used as the input's placeholder."
+        },
+        {
+          "name": "onCommit",
+          "type": "(value: string) => void",
+          "description": "Called with the trimmed text on Enter, blur or Tab, only when it differs from `value`. An empty string means \"restore the default\". The parent updates `value`."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "description": "The field's name (e.g. \"Section title\"). Names the input, and the pencil as \"Edit {label}\"."
+        },
+        {
+          "name": "editLabel",
+          "type": "string",
+          "description": "Accessible name of the pencil. Defaults to \"Edit {label}\"."
+        },
+        {
+          "name": "as",
+          "type": "'span' | 'div' | 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'",
+          "default": "\"span\"",
+          "description": "The element to render. Typography inherits from it, so a title keeps its heading's size and colour."
+        },
+        {
+          "name": "defaultEditing",
+          "type": "boolean",
+          "default": "false",
+          "description": "Opens in the editing state on mount, without moving focus."
+        }
+      ],
+      "dependencies": [
+        "@phosphor-icons/react",
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [
+        "--border-default",
+        "--border-focus",
+        "--button-icon-ghost-color",
+        "--button-icon-pad",
+        "--button-icon-size",
+        "--control-edge-color",
+        "--control-edge-style",
+        "--control-edge-width",
+        "--control-state-edge-width",
+        "--focus-ring-offset",
+        "--focus-ring-width",
+        "--motion-duration-150",
+        "--motion-easing-default",
+        "--radius-sm",
+        "--spacing-1",
+        "--spacing-2",
+        "--text-primary",
+        "--text-secondary",
+        "--text-tertiary"
+      ],
+      "example": "const [title, setTitle] = React.useState(\"\")\n\n<InlineEdit\n  as=\"h2\"\n  label=\"Section title\"\n  value={title}\n  defaultValue=\"Track record\"\n  onCommit={setTitle}\n/>\n"
+    },
     "input": {
       "category": "form",
       "description": "A text input component with focus and validation states.",
@@ -5353,6 +5487,10 @@
         "--border-error",
         "--border-focus",
         "--border-strong",
+        "--control-edge-color",
+        "--control-edge-style",
+        "--control-edge-width",
+        "--control-state-edge-width",
         "--field-control-bg",
         "--focus-ring-offset",
         "--focus-ring-width",
@@ -7033,6 +7171,78 @@
       ],
       "example": "<RadiusScale steps={[\n  { token: \"--radius-sm\", name: \"sm\", px: 2 },\n  { token: \"--radius-md\", name: \"md\", px: 4 },\n  { token: \"--radius-full\", name: \"full\", px: 9999 },\n]} />\n"
     },
+    "save-status": {
+      "category": "feedback",
+      "description": "Autosave readout — Saved / Saving / Unsaved / Couldn't save in a fixed-width slot that never reflows its row, with a retry mark after a failed save. aria-live polite; draws no edge.",
+      "when_to_use": [
+        "Showing where an autosaved value stands, beside the section or field it saves",
+        "Any editor with no Save button, driven by the useAutosave hook",
+        "Offering a retry after a save failed, without a toast"
+      ],
+      "when_not_to_use": [
+        "Confirming a one-off action the user just took — use SuccessFeedback or a toast",
+        "A save/cancel footer model — use the admin editor patterns' footer buttons",
+        "Conflicts between tabs or users — use ConflictBanner"
+      ],
+      "variants": {
+        "status": {
+          "saved": "Saved — muted, the resting state.",
+          "saving": "Saving — a write is in flight.",
+          "unsaved": "Unsaved — a change is waiting for the debounce.",
+          "refused": "Couldn't save — validation refused the value or the write failed; shows a retry mark when onRetry is passed."
+        }
+      },
+      "props": [
+        {
+          "name": "status",
+          "type": "'saved' | 'saving' | 'unsaved' | 'refused'",
+          "description": "Where the value stands — pass useAutosave(...).status."
+        },
+        {
+          "name": "onRetry",
+          "type": "() => void",
+          "description": "Shows a retry mark while status is refused. Pass useAutosave(...).retry."
+        },
+        {
+          "name": "labels",
+          "type": "Partial<Record<'saved' | 'saving' | 'unsaved' | 'refused', string>>",
+          "description": "Override any of the four labels, e.g. to translate them."
+        },
+        {
+          "name": "retryLabel",
+          "type": "string",
+          "default": "\"Retry saving\"",
+          "description": "Accessible name of the retry mark."
+        }
+      ],
+      "dependencies": [
+        "@phosphor-icons/react",
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [
+        "--border-focus",
+        "--button-icon-ghost-color",
+        "--button-icon-pad",
+        "--button-icon-size",
+        "--focus-ring-offset",
+        "--focus-ring-width",
+        "--font-size-xs",
+        "--motion-duration-150",
+        "--motion-easing-default",
+        "--radius-sm",
+        "--save-status-font-family",
+        "--save-status-letter-spacing",
+        "--save-status-text-transform",
+        "--save-status-width",
+        "--spacing-1",
+        "--spacing-2",
+        "--text-error",
+        "--text-primary",
+        "--text-secondary",
+        "--text-tertiary"
+      ],
+      "example": "const autosave = useAutosave(bio, saveBio)\n\n<SaveStatus status={autosave.status} onRetry={autosave.retry} />\n"
+    },
     "score-indicator": {
       "category": "admin",
       "description": "Compact circular ring visualization for percentage or ratio metrics — health score, uptime, engagement, capacity.",
@@ -7595,6 +7805,10 @@
         "--border-error",
         "--border-focus",
         "--border-strong",
+        "--control-edge-color",
+        "--control-edge-style",
+        "--control-edge-width",
+        "--control-state-edge-width",
         "--field-control-bg",
         "--field-menu-bg",
         "--focus-ring-width",
@@ -9417,10 +9631,16 @@
         "@radix-ui/react-switch"
       ],
       "tokens_used": [
+        "--_switch-knob-size",
+        "--_switch-knob-start",
+        "--_switch-pad",
         "--border-default",
         "--border-error",
         "--border-focus",
         "--border-strong",
+        "--control-edge-style",
+        "--control-edge-width",
+        "--control-state-edge-width",
         "--focus-ring-width",
         "--interactive-primary-bg",
         "--motion-duration-150",
@@ -9428,7 +9648,11 @@
         "--primary",
         "--shadow-sm",
         "--surface-page",
-        "--switch-track-bg"
+        "--switch-edge-color",
+        "--switch-knob-inset",
+        "--switch-track-bg",
+        "--switch-track-height",
+        "--switch-track-width"
       ],
       "example": "<div style={{ display: \"flex\", alignItems: \"center\", gap: \"0.5rem\" }}>\n  <Switch id=\"notifications\" />\n  <Label htmlFor=\"notifications\">Enable notifications</Label>\n</div>\n"
     },
@@ -9704,6 +9928,10 @@
         "--border-default",
         "--border-focus",
         "--border-strong",
+        "--control-edge-color",
+        "--control-edge-style",
+        "--control-edge-width",
+        "--control-state-edge-width",
         "--focus-ring-width",
         "--font-size-sm",
         "--font-size-xs",
@@ -9754,6 +9982,7 @@
           "primary",
           "secondary",
           "tertiary",
+          "warning",
           "inherit"
         ],
         "leading": [
@@ -9783,7 +10012,7 @@
         },
         {
           "name": "color",
-          "type": "'primary' | 'secondary' | 'tertiary' | 'inherit'",
+          "type": "'primary' | 'secondary' | 'tertiary' | 'warning' | 'inherit'",
           "default": "'primary'"
         },
         {
@@ -9811,9 +10040,25 @@
         "--line-height-relaxed",
         "--line-height-snug",
         "--line-height-tight",
+        "--text-lg-font-size",
+        "--text-lg-letter-spacing",
+        "--text-lg-text-transform",
+        "--text-md-font-size",
+        "--text-md-letter-spacing",
+        "--text-md-text-transform",
         "--text-primary",
         "--text-secondary",
-        "--text-tertiary"
+        "--text-sm-font-size",
+        "--text-sm-letter-spacing",
+        "--text-sm-text-transform",
+        "--text-tertiary",
+        "--text-warning",
+        "--text-xl-font-size",
+        "--text-xl-letter-spacing",
+        "--text-xl-text-transform",
+        "--text-xs-font-size",
+        "--text-xs-letter-spacing",
+        "--text-xs-text-transform"
       ],
       "example": "<Text>Default body text paragraph.</Text>\n\n<Text size=\"sm\" color=\"secondary\">\n  Helper text or caption.\n</Text>\n\n<Text as=\"span\" weight=\"semibold\" size=\"lg\">\n  Inline emphasized text\n</Text>\n"
     },
@@ -9859,6 +10104,10 @@
         "--border-error",
         "--border-focus",
         "--border-strong",
+        "--control-edge-color",
+        "--control-edge-style",
+        "--control-edge-width",
+        "--control-state-edge-width",
         "--focus-ring-width",
         "--font-size-base",
         "--font-size-sm",
@@ -10031,6 +10280,74 @@
       ],
       "example": "<Timeline>\n  <TimelineItem status=\"complete\">\n    <TimelineContent>\n      <TimelineTitle>Order placed</TimelineTitle>\n      <TimelineTimestamp dateTime=\"2024-01-15\">Jan 15</TimelineTimestamp>\n    </TimelineContent>\n  </TimelineItem>\n  <TimelineItem status=\"active\">\n    <TimelineContent>\n      <TimelineTitle>In transit</TimelineTitle>\n      <TimelineDescription>Package is on the way.</TimelineDescription>\n    </TimelineContent>\n  </TimelineItem>\n  <TimelineItem status=\"upcoming\">\n    <TimelineContent>\n      <TimelineTitle>Delivered</TimelineTitle>\n    </TimelineContent>\n  </TimelineItem>\n</Timeline>\n"
     },
+    "tin-input": {
+      "category": "form",
+      "description": "A write-only, masked 9-digit TIN/EIN input with a last-four echo that never re-displays the value.",
+      "when_to_use": [
+        "Collecting a Social Security number or an EIN (a W-9, a payout or tax form)",
+        "Any 9-digit taxpayer ID that is stored server-side and must never be shown back",
+        "Showing a TIN already on file by its last four, with a way to replace it"
+      ],
+      "when_not_to_use": [
+        "Passwords (use PasswordInput — it has a show/hide toggle, which a TIN must not)",
+        "Verification codes (use OTPInput)",
+        "Numbers the user needs to read back or edit in place (use Input or NumberInput)"
+      ],
+      "props": [
+        {
+          "name": "kind",
+          "type": "'ssn' | 'ein'",
+          "required": true,
+          "description": "Display grouping — SSN"
+        },
+        {
+          "name": "onValueChange",
+          "type": "(digits: string | null) => void",
+          "required": true,
+          "description": "Called with the 9 digits once the entry is complete, and with null while it is incomplete or cleared."
+        },
+        {
+          "name": "lastFour",
+          "type": "string",
+          "description": "Last four digits of a TIN already on file. Renders a read-only \"On file · ending 1234\" with a Replace button. A new value brings the echo back after a Replace. Only ever pass four digits."
+        },
+        {
+          "name": "onReplace",
+          "type": "() => void",
+          "description": "Called when Replace swaps the on-file echo for an empty field."
+        },
+        {
+          "name": "error",
+          "type": "string",
+          "description": "Error message, rendered as a FieldError and bound by aria-describedby; sets aria-invalid."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "default": "md",
+          "description": "Size of the field and the Replace button. lg meets 44px touch targets."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "default": "false",
+          "description": "Disables the field and the Replace button."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "description": "Id for the input, so a FieldLabel htmlFor associates the label."
+        }
+      ],
+      "dependencies": [
+        "@loworbitstudio/visor-core"
+      ],
+      "tokens_used": [
+        "--spacing-2",
+        "--text-secondary"
+      ],
+      "example": "<Field>\n  <FieldLabel htmlFor=\"tin\">Social Security number</FieldLabel>\n  <TinInput id=\"tin\" kind=\"ssn\" onValueChange={setTin} />\n</Field>\n\n<TinInput id=\"tin\" kind=\"ein\" lastFour=\"6789\" onValueChange={setTin} />\n"
+    },
     "toast": {
       "category": "feedback",
       "description": "Ephemeral notification messages that appear and auto-dismiss.",
@@ -12047,6 +12364,68 @@
         }
       ]
     },
+    "use-autosave": {
+      "description": "Autosave for one value: debounces the write (600ms), runs one write at a time so the newest value wins, flushes a pending change on pagehide, tab hide and unmount, and reports saved · saving · unsaved · refused with retry().",
+      "params": [
+        {
+          "name": "value",
+          "type": "T",
+          "required": true,
+          "description": "The value to keep saved. The first render's value counts as saved and is not written."
+        },
+        {
+          "name": "write",
+          "type": "(value: T, context: { leaving: boolean }) => unknown",
+          "required": true,
+          "description": "Persists the value. Return a promise; a rejection (or a throw) puts the hook in refused. `leaving` is true when the page is being left, so use `keepalive` or `sendBeacon`."
+        },
+        {
+          "name": "options.delay",
+          "type": "number",
+          "required": false,
+          "description": "Debounce in milliseconds after the last change. Defaults to 600."
+        },
+        {
+          "name": "options.validate",
+          "type": "(value: T) => boolean",
+          "required": false,
+          "description": "Return false to refuse a value. A refused value is never written, stays in the control, and puts the hook in refused."
+        },
+        {
+          "name": "options.isEqual",
+          "type": "(a: T, b: T) => boolean",
+          "required": false,
+          "description": "Decides whether a value is already saved. Defaults to Object.is; pass one for object values."
+        }
+      ],
+      "returns": [
+        {
+          "name": "status",
+          "type": "'saved' | 'saving' | 'unsaved' | 'refused'",
+          "description": "Where the value stands. Pass it to SaveStatus."
+        },
+        {
+          "name": "reason",
+          "type": "'invalid' | 'failed' | null",
+          "description": "Why the hook is refused — validate rejected the value, or write failed."
+        },
+        {
+          "name": "error",
+          "type": "unknown",
+          "description": "What write threw or rejected with, while reason is failed."
+        },
+        {
+          "name": "retry",
+          "type": "() => void",
+          "description": "Write the current value now."
+        },
+        {
+          "name": "flush",
+          "type": "() => void",
+          "description": "Write a pending change now instead of waiting for the debounce."
+        }
+      ]
+    },
     "use-click-outside": {
       "description": "Fires a callback when a click or touch event occurs outside the referenced element. Useful for closing dropdowns and popovers.",
       "params": [
@@ -12739,6 +13118,7 @@
       "offline-banner",
       "popover",
       "progress",
+      "save-status",
       "skeleton",
       "slow-network-bar",
       "success-feedback",
@@ -12786,6 +13166,7 @@
       "file-upload",
       "form",
       "form-error",
+      "inline-edit",
       "input",
       "label",
       "number-input",
@@ -12801,6 +13182,7 @@
       "switch",
       "tag-input",
       "textarea",
+      "tin-input",
       "toggle-group"
     ],
     "media": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "CLI for the Visor design system — add components, hooks, and utilities to your project.",
   "type": "module",
   "bin": {
@@ -46,7 +46,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1021.0",
     "@babel/parser": "^7.26.0",
-    "@loworbitstudio/visor-theme-engine": "^0.21.0",
+    "@loworbitstudio/visor-theme-engine": "^0.22.0",
     "commander": "^13.1.0",
     "diff": "^8.0.4",
     "picocolors": "^1.1.1",