{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "sync-status",
  "title": "SyncStatus",
  "description": "One line that says where the person's changes are: Saved, Saving…, Offline (kept on this device) or Not saved (the server refused the changes), each with its icon, and Retry while there is a problem.",
  "registryDependencies": [
    "@ouro/lib-announce",
    "@ouro/lib-class-name-check",
    "@ouro/lib-cn",
    "@ouro/lib-env",
    "@ouro/lib-touch-target",
    "@ouro/lib-use-dev-messages"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/sync-status/sync-status.tsx",
      "content": "\"use client\";\n\nimport { useCallback, useEffect, useLayoutEffect, useMemo, useRef, type HTMLAttributes, type JSX, type Ref } from \"react\";\nimport { announce } from \"@/registry/ouro/lib/ouro/announce\";\nimport { useAppearanceClassNameCheck } from \"@/registry/ouro/lib/ouro/class-name-check\";\nimport { cn } from \"@/registry/ouro/lib/ouro/cn\";\nimport { TouchTarget } from \"@/registry/ouro/lib/ouro/touch-target\";\nimport { useDevWarnings } from \"@/registry/ouro/lib/ouro/use-dev-messages\";\n\n/** Where the person's changes are. */\nexport type SyncState = \"saved\" | \"saving\" | \"offline\" | \"error\";\n\n/**\n * The words for each state, for apps in other languages or to say what is saved.\n *\n * @claim \"The words for each state, for\" registry/ouro/components/ouro/sync-status/sync-status.test.tsx verify:testExists(registry/ouro/components/ouro/sync-status/sync-status.test.tsx::SyncStatus > takes words in another language, and keeps the defaults for the rest)\n */\nexport interface SyncStatusLabels {\n  /** Once changes reached the server. @default \"Saved\" */\n  saved?: string | undefined;\n  /** While changes travel. @default \"Saving…\" */\n  saving?: string | undefined;\n  /** While changes wait on this device. @default \"Offline: changes are kept on this device\" */\n  offline?: string | undefined;\n  /** When the server refused the changes. @default \"Not saved: the server refused the changes\" */\n  error?: string | undefined;\n  /** The retry button's label. @default \"Retry\" */\n  retry?: string | undefined;\n}\n\n/** The props SyncStatus adds to the `<div>` attributes it passes through. */\nexport interface SyncStatusOwnProps {\n  /**\n   * `saved` once changes reached the server, `saving` while they travel, `offline` while they\n   * wait on this device, `error` when the server refused them.\n   */\n  status: SyncState | (string & { 'Use \"saved\", \"saving\", \"offline\" or \"error\"': never });\n  /**\n   * The words for each state.\n   *\n   * @claim \"The words for each state\" registry/ouro/components/ouro/sync-status/sync-status.test.tsx verify:testExists(registry/ouro/components/ouro/sync-status/sync-status.test.tsx::SyncStatus > takes words in another language, and keeps the defaults for the rest)\n   */\n  labels?: SyncStatusLabels | undefined;\n  /** Shows Retry while `offline` or `error`, and is called when it is pressed. */\n  onRetry?: (() => void) | undefined;\n  /** Layout only: margins, placement (`mt-3`). Appearance classes warn in development. */\n  className?: string | undefined;\n  ref?: Ref<HTMLDivElement> | undefined;\n\n  /** Not a prop. Ouro UI says `status`: `<SyncStatus status=\"saving\" />`. */\n  state?: { 'Use status=\"saving\"': never };\n  /** Not a prop. Ouro UI says `status`: `<SyncStatus status=\"offline\" />`. */\n  online?: { 'Use status=\"offline\" when the device is offline': never };\n}\n\n/** Props for {@link SyncStatus}: its own props and the `<div>` attributes it passes through. */\nexport type SyncStatusProps = Omit<HTMLAttributes<HTMLDivElement>, keyof SyncStatusOwnProps> & SyncStatusOwnProps;\n\nconst states: readonly SyncState[] = [\"saved\", \"saving\", \"offline\", \"error\"];\nconst words: Record<keyof SyncStatusLabels, string> = {\n  saved: \"Saved\",\n  saving: \"Saving…\",\n  offline: \"Offline: changes are kept on this device\",\n  error: \"Not saved: the server refused the changes\",\n  retry: \"Retry\",\n};\nconst problems = new Set<SyncState>([\"offline\", \"error\"]);\n// Match Celebrate's time for the triggering control's state announcement (a switch's \"off\").\n// This fixed delay does not detect when a screen reader has finished speaking. Recovery keeps\n// the default delay: Retry's save moves focus to this line, and VoiceOver's usage hint for it\n// starts about then and swallows a later message.\nconst SPEAK_DELAY_MS = 1500;\n\nconst tones: Record<SyncState, string> = {\n  saved: \"text-[color-mix(in_oklab,var(--muted-foreground)_88%,var(--foreground))]\",\n  saving: \"text-[color-mix(in_oklab,var(--muted-foreground)_88%,var(--foreground))]\",\n  offline: \"text-[color-mix(in_oklab,var(--warning)_70%,var(--foreground))]\",\n  error: \"text-[color-mix(in_oklab,var(--destructive)_80%,var(--foreground))]\",\n};\n\nconst icons: Record<SyncState, JSX.Element> = {\n  saved: <path d=\"M20 6 9 17l-5-5\" />,\n  saving: <path d=\"M21 12a9 9 0 1 1-6.22-8.56\" />,\n  offline: (\n    <>\n      <path d=\"m2 2 20 20\" />\n      <path d=\"M5.78 5.78A7 7 0 0 0 6.5 19H17\" />\n      <path d=\"M21.5 15.5A4.5 4.5 0 0 0 17.5 9h-1.79A7 7 0 0 0 9.5 5.08\" />\n    </>\n  ),\n  error: (\n    <>\n      <circle cx=\"12\" cy=\"12\" r=\"10\" />\n      <path d=\"M12 8v4M12 16h.01\" />\n    </>\n  ),\n};\n\nfunction Line({\n  state,\n  label,\n  retry,\n  onRetry,\n  retryRef,\n}: {\n  state: SyncState;\n  label: string;\n  retry: string;\n  onRetry: (() => void) | undefined;\n  retryRef?: Ref<HTMLButtonElement> | undefined;\n}): JSX.Element {\n  const hasRetry = onRetry !== undefined && problems.has(state);\n  return (\n    <>\n      <svg\n        aria-hidden=\"true\"\n        viewBox=\"0 0 24 24\"\n        fill=\"none\"\n        stroke=\"currentColor\"\n        strokeWidth=\"2\"\n        strokeLinecap=\"round\"\n        strokeLinejoin=\"round\"\n        className={cn(\"me-1.5 inline-block size-4 shrink-0 align-[-0.1875rem]\", state === \"saving\" && \"motion-safe:animate-[ouro-spin_1s_linear_infinite]\")}\n      >\n        {icons[state]}\n      </svg>\n      <span>{label}</span>\n      {hasRetry ? (\n        <button\n          ref={retryRef}\n          type=\"button\"\n          data-ouro-control=\"sync-status\"\n          data-ouro-part=\"retry\"\n          onClick={onRetry}\n          className=\"relative ms-2 cursor-pointer rounded-ouro-sm border-0 bg-transparent p-0 font-[inherit] text-[length:inherit] leading-[inherit] font-medium text-foreground underline underline-offset-4 outline-ring outline-offset-2 focus-visible:outline-2 focus-visible:outline-solid pointer-fine:hover:decoration-2\"\n        >\n          <TouchTarget />\n          {retry}\n        </button>\n      ) : null}\n    </>\n  );\n}\n\n/**\n * One line that says where the person's changes are: Saved, Saving…, Offline (kept on this\n * device) or Not saved (the server refused the changes), each with its icon, and Retry while there is a problem. Screen\n * readers hear it only when a problem starts and when it clears, so every save is not\n * narrated. It keeps the height of its longest state, so a change never moves the page.\n * When Retry goes away while it has focus (the save it started is under way), focus moves to\n * the status line, so the person stays where they were rather than at the top of the page.\n *\n * Use `toast()` instead to confirm a single action, and `Alert` for a problem that blocks the page.\n *\n * @group Feedback\n * @see https://ui.ouroboros.bot/docs/sync-status\n *\n * @example\n * <SyncStatus status={navigator.onLine ? (pending ? \"saving\" : \"saved\") : \"offline\"} onRetry={flush} />\n * @claim \"One line that says where the\" registry/ouro/components/ouro/sync-status/sync-status.test.tsx verify:testExists(registry/ouro/components/ouro/sync-status/sync-status.test.tsx::SyncStatus > speaks when a problem starts and when changes are saved again, and not for every save)\n * @claim \"Screen readers hear it only when\" registry/ouro/components/ouro/sync-status/sync-status.test.tsx verify:testExists(registry/ouro/components/ouro/sync-status/sync-status.test.tsx::SyncStatus > speaks when a problem starts and when changes are saved again, and not for every save)\n * @claim \"It keeps the height of its\" registry/ouro/components/ouro/sync-status/sync-status.test.tsx verify:testExists(registry/ouro/components/ouro/sync-status/sync-status.test.tsx::SyncStatus > keeps one height whichever state it shows, so the page never moves)\n */\nexport function SyncStatus(props: SyncStatusProps): JSX.Element {\n  const {\n    status: statusProp,\n    labels,\n    onRetry,\n    className,\n    // Guard props (hint types), dropped here so they never reach the DOM.\n    state,\n    online,\n    ...rest\n  } = props;\n  const status: SyncState = (states as readonly string[]).includes(statusProp) ? (statusProp as SyncState) : \"saved\";\n  // Merged once per labels object, so an app that keeps its labels in a constant merges them once.\n  const word = useMemo(() => ({ ...words, ...Object.fromEntries(Object.entries(labels ?? {}).filter(([, value]) => value !== undefined)) }) as Record<keyof SyncStatusLabels, string>, [labels]);\n  useAppearanceClassNameCheck(\n    \"SyncStatus\",\n    className,\n    process.env.NODE_ENV !== \"production\"\n      ? (token: string) => `remove \"${token}\"; SyncStatus takes its colors from the theme`\n      : /* istanbul ignore next @preserve -- production only */ \"\",\n  );\n  useDevWarnings(\n    \"SyncStatus\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [\n          status !== statusProp && [`status=\"${String(statusProp)}\" is not a status; use \"saved\", \"saving\", \"offline\" or \"error\"`, '<SyncStatus status=\"saving\" />'],\n          state !== undefined && [\"state is not a prop\", `<SyncStatus status=\"${typeof state === \"string\" ? state : \"saving\"}\" />`],\n          online !== undefined && [\"online is not a prop\", '<SyncStatus status=\"offline\" />'],\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n  // Spoken when a problem starts, and when changes are saved again after one.\n  const troubled = useRef(false);\n  useEffect(() => {\n    if (problems.has(status)) {\n      troubled.current = true;\n      return announce(word[status], { delayMs: SPEAK_DELAY_MS });\n    } else if (status === \"saved\" && troubled.current) {\n      return announce(word.saved, { onWrite: () => { troubled.current = false; } });\n    }\n    // The words change with the status; a new translation alone is not news.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [status]);\n\n  // Retry leaves with its problem. React detaches its ref before it removes the button, so focus\n  // is still on it then; once the commit is done, focus moves to the line instead of the page.\n  const line = useRef<HTMLParagraphElement>(null);\n  const retryHadFocus = useRef(false);\n  // A ref that returns a cleanup is only ever called with the element.\n  const retryRef = useCallback(\n    (node: HTMLButtonElement | null) => () => {\n      retryHadFocus.current = node === document.activeElement;\n    },\n    [],\n  );\n  useLayoutEffect(() => {\n    if (!retryHadFocus.current) return;\n    retryHadFocus.current = false;\n    line.current!.focus();\n  });\n\n  return (\n    <div {...rest} data-ouro=\"sync-status\" data-status={status} className={cn(\"grid min-w-0 text-sm leading-5\", className)}>\n      {states.map((reserved) => (\n        <p key={reserved} aria-hidden=\"true\" className=\"invisible m-0 [grid-area:1/1]\">\n          <Line state={reserved} label={word[reserved]} retry={word.retry} onRetry={undefined} />\n          {onRetry && problems.has(reserved) ? <span className=\"ms-2 font-medium\">{word.retry}</span> : null}\n        </p>\n      ))}\n      <p\n        ref={line}\n        tabIndex={-1}\n        className={cn(\"m-0 rounded-ouro-sm outline-ring outline-offset-2 [grid-area:1/1] focus-visible:outline-2 focus-visible:outline-solid\", tones[status])}\n      >\n        <Line state={status} label={word[status]} retry={word.retry} onRetry={onRetry} retryRef={retryRef} />\n      </p>\n    </div>\n  );\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/sync-status/sync-status.tsx"
    }
  ],
  "docs": "One line that says where the person's changes are: Saved, Saving…, Offline (kept on this device) or Not saved (the server refused the changes), each with its icon, and Retry while there is a problem. Import: import { SyncStatus } from \"@/components/ouro/sync-status/sync-status\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: the helpers it imports in lib/ouro. Needs ouro-base in your stylesheet: add that item once per app, from the same place as this one, if you have not. Docs: https://ui.ouroboros.bot/docs/sync-status.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}