@misoto22/folio 0.0.0 → 0.16.0

package/dist/index.js

@@ -0,0 +1,80 @@
+export * from "./lib/overlay-container.js";
+import { BRAND } from "./tokens/brand.js";
+import { cn } from "./lib/cn.js";
+import { CONTROL_BASE, CONTROL_BORDER, isInvalid } from "./lib/control.js";
+import { useSelectionIndicator } from "./lib/useSelectionIndicator.js";
+export * from "./components/Button/Button.js";
+export * from "./components/FloatingIconButton/FloatingIconButton.js";
+export * from "./components/Text/Text.js";
+export * from "./components/Heading/Heading.js";
+export * from "./components/Code/Code.js";
+export * from "./components/CodeBlock/CodeBlock.js";
+export * from "./components/Markdown/Markdown.js";
+export * from "./components/Badge/Badge.js";
+export * from "./components/Tag/Tag.js";
+export * from "./components/Kbd/Kbd.js";
+export * from "./components/Avatar/Avatar.js";
+export * from "./components/StatusDot/StatusDot.js";
+export * from "./components/Metric/Metric.js";
+export * from "./components/StatusPill/StatusPill.js";
+export * from "./components/LinkArrow/LinkArrow.js";
+export * from "./components/Separator/Separator.js";
+export * from "./components/Timestamp/Timestamp.js";
+export * from "./components/FigureBand/FigureBand.js";
+export * from "./components/Spinner/Spinner.js";
+export * from "./components/Skeleton/Skeleton.js";
+export * from "./components/Progress/Progress.js";
+export * from "./components/Alert/Alert.js";
+export * from "./components/EmptyState/EmptyState.js";
+export * from "./components/ErrorState/ErrorState.js";
+export * from "./components/Toast/Toast.js";
+export * from "./components/Field/Field.js";
+export * from "./components/ColorPicker/ColorPicker.js";
+export * from "./components/Combobox/Combobox.js";
+export * from "./components/DatePicker/DatePicker.js";
+export * from "./components/NumberField/NumberField.js";
+export * from "./components/Slider/Slider.js";
+export * from "./components/ToggleGroup/ToggleGroup.js";
+export * from "./components/Input/Input.js";
+export * from "./components/Textarea/Textarea.js";
+export * from "./components/Select/Select.js";
+export * from "./components/NativeSelect/NativeSelect.js";
+export * from "./components/Checkbox/Checkbox.js";
+export * from "./components/RadioGroup/RadioGroup.js";
+export * from "./components/Switch/Switch.js";
+export * from "./components/Dialog/Dialog.js";
+export * from "./components/DropdownMenu/DropdownMenu.js";
+export * from "./components/Tooltip/Tooltip.js";
+export * from "./components/Popover/Popover.js";
+export * from "./components/Sheet/Sheet.js";
+export * from "./components/ContextMenu/ContextMenu.js";
+export * from "./components/Command/Command.js";
+export * from "./components/SearchableMenu/SearchableMenu.js";
+export * from "./components/Tabs/Tabs.js";
+export * from "./components/Accordion/Accordion.js";
+export * from "./components/Collapsible/Collapsible.js";
+export * from "./components/Breadcrumb/Breadcrumb.js";
+export * from "./components/Pagination/Pagination.js";
+export * from "./components/NavItem/NavItem.js";
+export * from "./components/Sidebar/Sidebar.js";
+export * from "./components/Card/Card.js";
+export * from "./components/Table/Table.js";
+export * from "./components/DescriptionList/DescriptionList.js";
+export * from "./components/Toolbar/Toolbar.js";
+export * from "./components/AspectRatio/AspectRatio.js";
+export * from "./components/Calendar/Calendar.js";
+export * from "./components/ScrollArea/ScrollArea.js";
+export * from "./components/AppShell/AppShell.js";
+export * from "./components/PageHeader/PageHeader.js";
+export * from "./components/Article/Article.js";
+export * from "./components/Diagram/Diagram.js";
+export * from "./components/Steps/Steps.js";
+export {
+  BRAND,
+  CONTROL_BASE,
+  CONTROL_BORDER,
+  cn,
+  isInvalid,
+  useSelectionIndicator
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @misoto22/folio — public entry.\n *\n * Components export from here; the look ships separately as CSS:\n *\n *   import '@misoto22/folio/styles.css'    // compiled Tailwind + tokens + fonts\n *\n * or, for an app that already compiles Tailwind itself, the portable layers on\n * their own:\n *\n *   import '@misoto22/folio/tokens.css'    // primitives, plus data-mode and data-density\n *   import '@misoto22/folio/semantic.css'  // roles\n *   import '@misoto22/folio/themes.css'    // the other six theming axes\n *   import '@misoto22/folio/keyframes.css' // motion\n *\n * All four, or the theming attributes are attributes that do nothing: every\n * axis but `data-mode` and `data-density` is declared only in `themes.css`, and\n * an app that skips it writes `data-radius=\"sharp\"` and gets no error, no\n * warning and no corner.\n *\n * Everything below is a consumer contract. Adding an export is cheap; changing\n * or removing one is a breaking change (DESIGN-API-001).\n */\n\n// ─── Utilities ───\nexport * from './lib/overlay-container'\n\n// ─── Tokens ───\nexport { BRAND } from './tokens/brand'\nexport type { BrandColor } from './tokens/brand'\n\n// ─── Utilities ───\nexport { cn } from './lib/cn'\nexport { CONTROL_BASE, CONTROL_BORDER, isInvalid } from './lib/control'\nexport { useSelectionIndicator } from './lib/useSelectionIndicator'\nexport type { IndicatorStyle } from './lib/useSelectionIndicator'\n\n// ─── Actions ───\nexport * from './components/Button/Button'\nexport * from './components/FloatingIconButton/FloatingIconButton'\n\n// ─── Display ───\nexport * from './components/Text/Text'\nexport * from './components/Heading/Heading'\nexport * from './components/Code/Code'\nexport * from './components/CodeBlock/CodeBlock'\nexport * from './components/Markdown/Markdown'\nexport * from './components/Badge/Badge'\nexport * from './components/Tag/Tag'\nexport * from './components/Kbd/Kbd'\nexport * from './components/Avatar/Avatar'\nexport * from './components/StatusDot/StatusDot'\nexport * from './components/Metric/Metric'\nexport * from './components/StatusPill/StatusPill'\nexport * from './components/LinkArrow/LinkArrow'\nexport * from './components/Separator/Separator'\nexport * from './components/Timestamp/Timestamp'\nexport * from './components/FigureBand/FigureBand'\n\n// ─── Feedback ───\nexport * from './components/Spinner/Spinner'\nexport * from './components/Skeleton/Skeleton'\nexport * from './components/Progress/Progress'\nexport * from './components/Alert/Alert'\nexport * from './components/EmptyState/EmptyState'\nexport * from './components/ErrorState/ErrorState'\nexport * from './components/Toast/Toast'\n\n// ─── Forms ───\nexport * from './components/Field/Field'\nexport * from './components/ColorPicker/ColorPicker'\nexport * from './components/Combobox/Combobox'\nexport * from './components/DatePicker/DatePicker'\nexport * from './components/NumberField/NumberField'\nexport * from './components/Slider/Slider'\nexport * from './components/ToggleGroup/ToggleGroup'\nexport * from './components/Input/Input'\nexport * from './components/Textarea/Textarea'\nexport * from './components/Select/Select'\nexport * from './components/NativeSelect/NativeSelect'\nexport * from './components/Checkbox/Checkbox'\nexport * from './components/RadioGroup/RadioGroup'\nexport * from './components/Switch/Switch'\n\n// ─── Overlays ───\nexport * from './components/Dialog/Dialog'\nexport * from './components/DropdownMenu/DropdownMenu'\nexport * from './components/Tooltip/Tooltip'\nexport * from './components/Popover/Popover'\nexport * from './components/Sheet/Sheet'\nexport * from './components/ContextMenu/ContextMenu'\nexport * from './components/Command/Command'\nexport * from './components/SearchableMenu/SearchableMenu'\n\n// ─── Navigation ───\nexport * from './components/Tabs/Tabs'\nexport * from './components/Accordion/Accordion'\nexport * from './components/Collapsible/Collapsible'\nexport * from './components/Breadcrumb/Breadcrumb'\nexport * from './components/Pagination/Pagination'\nexport * from './components/NavItem/NavItem'\nexport * from './components/Sidebar/Sidebar'\n\n// ─── Surfaces / layout ───\nexport * from './components/Card/Card'\nexport * from './components/Table/Table'\nexport * from './components/DescriptionList/DescriptionList'\nexport * from './components/Toolbar/Toolbar'\nexport * from './components/AspectRatio/AspectRatio'\nexport * from './components/Calendar/Calendar'\nexport * from './components/ScrollArea/ScrollArea'\nexport * from './components/AppShell/AppShell'\nexport * from './components/PageHeader/PageHeader'\nexport * from './components/Article/Article'\nexport * from './components/Diagram/Diagram'\nexport * from './components/Steps/Steps'\n"],"mappings":"AAyBA,cAAc;AAGd,SAAS,aAAa;AAItB,SAAS,UAAU;AACnB,SAAS,cAAc,gBAAgB,iBAAiB;AACxD,SAAS,6BAA6B;AAItC,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/dist/keyframes.css

@@ -0,0 +1,300 @@
+/* ==========================================================================
+   MOTION — the system's named animations
+   --------------------------------------------------------------------------
+   Portable, like tokens.css: plain CSS, no Tailwind. Every component that
+   animates reaches for one of these rather than declaring its own, so the
+   whole system arrives and leaves on the same curve.
+
+   Durations are NOT baked in here — a keyframe says what moves, a call site
+   says how fast, using --fast / --mid / --slow. Reduced motion is honoured in
+   one place, at the bottom.
+   ========================================================================== */
+
+.folio-tabs-list { position: relative; isolation: isolate; }
+.folio-tabs-list[data-swipe] { touch-action: pan-y; user-select: none; }
+.folio-tabs-list[data-dragging] { cursor: grabbing; }
+.folio-tabs-list[data-orientation=horizontal][data-measured]::before { content: ''; position: absolute; z-index: 0; pointer-events: none; left: 0; top: calc(var(--tab-y) + var(--tab-height) - 2px); width: var(--tab-width); height: 2px; background: var(--accent); transform: translateX(calc(var(--tab-x) + var(--tab-drag-x, 0px))); transition: transform var(--duration-base) var(--ease-out-expo), width var(--duration-base) var(--ease-out-expo); }
+.folio-tabs-list [role=tab] { position: relative; z-index: 1; }
+/* Keep the focus treatment inside the scrolling strip so no outline is clipped. */
+.folio-tabs-list [role=tab]:focus { outline: none; }
+.folio-tabs-list [role=tab]:focus-visible { outline: none; background-color: var(--paper-2); box-shadow: inset 0 0 0 1px var(--rule-2); border-radius: 4px; }
+.folio-tabs-list[data-orientation=horizontal][data-measured] [role=tab][data-state=active] { border-bottom-color: transparent; }
+.folio-tabs-list[data-dragging]::before { transition-duration: 0ms; }
+.folio-tabs-panel[data-state=active] { animation: folio-tab-in var(--duration-base) var(--ease-out-expo); }
+.folio-tabs-panel[hidden] { display: none; }
+@keyframes folio-tab-in { from { opacity: 0; transform: translateX(var(--tab-enter-x, 0px)); } to { opacity: 1; transform: translateX(0); } }
+/* Recharts clears the browser's SVG outline. Keep a chart's keyboard cursor as
+   visible as every other control, without asking hosts to add a local rule. In
+   the base layer, beside the one `:focus-visible` indicator it restores. */
+@layer base {
+  [data-slot='chart'] svg.recharts-surface[tabindex]:focus-visible {
+    outline: var(--focus-w) solid var(--focus);
+    outline-offset: var(--focus-off);
+  }
+}
+.folio-sheet { translate: none; --sheet-x: 0%; --sheet-y: 0%; }
+.folio-sheet[data-side=top] { --sheet-y: -100%; }
+.folio-sheet[data-side=bottom] { --sheet-y: 100%; }
+.folio-sheet[data-side=start] { --sheet-x: -100%; }
+.folio-sheet[data-side=end] { --sheet-x: 100%; }
+.folio-sheet[data-side=start]:dir(rtl) { --sheet-x: 100%; }
+.folio-sheet[data-side=end]:dir(rtl) { --sheet-x: -100%; }
+.folio-sheet[data-state=open] { animation: folio-sheet-in var(--duration-base) var(--ease-out-expo); }
+.folio-sheet[data-state=closed] { animation: folio-sheet-out var(--duration-fast) var(--ease); }
+@keyframes folio-sheet-in { from { transform: translate(var(--sheet-x), var(--sheet-y)); } to { transform: translate(0, 0); } }
+@keyframes folio-sheet-out { from { transform: translate(0, 0); } to { transform: translate(var(--sheet-x), var(--sheet-y)); } }
+
+/* A surface arriving in place — a panel, a menu, a tab's contents. Short and
+   small: the page did not change, only part of it. */
+@keyframes folio-panel-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+/* An ANCHORED panel arriving, growing from wherever its trigger is.
+   Radix puts that point on the wrapper as --radix-popper-transform-origin; the
+   call site passes it down. Origin is what makes this read as an animation
+   rather than as a flicker: four pixels of travel over 130ms is technically
+   motion and perceptually nothing, which is what "the menu has no animation"
+   turned out to mean. */
+@keyframes folio-pop-in {
+  from {
+    opacity: 0;
+    transform: scale(0.96) translateY(-2px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+/* And leaving. A panel that vanishes on the frame the pointer lands elsewhere
+   reads as a bug in the page rather than as a thing that closed. */
+@keyframes folio-pop-out {
+  from {
+    opacity: 1;
+    transform: none;
+  }
+  to {
+    opacity: 0;
+    transform: scale(0.97) translateY(-2px);
+  }
+}
+
+/* A page arriving. Longer travel than a panel, because more of the view is
+   being replaced. */
+@keyframes folio-route-in {
+  from {
+    opacity: 0;
+    transform: translateY(12px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+/* An overlay's ground. No travel — a scrim does not slide, it appears. */
+@keyframes folio-fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes folio-fade-out {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+/* A toast entering from the edge it is docked to. */
+@keyframes folio-slide-in-right {
+  from {
+    opacity: 0;
+    transform: translateX(12px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+/* The system's "working" pulse — a dimming, not a shimmer. A skeleton that
+   shimmers implies a light source the White Reset does not have. */
+@keyframes folio-pulse {
+  0% {
+    opacity: 0.6;
+  }
+  50% {
+    opacity: 1;
+  }
+  100% {
+    opacity: 0.6;
+  }
+}
+
+/* The determinate/indeterminate bar's sweep. Travels 1.6× its own width so the
+   bar clears the track completely at each end. */
+@keyframes folio-sweep {
+  0% {
+    transform: translateX(-100%);
+  }
+  100% {
+    transform: translateX(400%);
+  }
+}
+
+/* The spinner. A rotation, and only a rotation — the arc that makes it read as
+   a spinner is drawn by the component's own conic gradient, not animated. */
+@keyframes folio-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* The three-dot "thinking" run, staggered by delay at the call site. */
+@keyframes folio-bounce-dot {
+  0%,
+  80%,
+  100% {
+    opacity: 0.25;
+    transform: translateY(0);
+  }
+  40% {
+    opacity: 1;
+    transform: translateY(-3px);
+  }
+}
+
+/* A live indicator's halo. Grows and dissolves; never loops a hard edge. */
+@keyframes folio-halo {
+  0% {
+    transform: scale(1);
+    opacity: 0.55;
+  }
+  70% {
+    transform: scale(2.6);
+    opacity: 0;
+  }
+  100% {
+    opacity: 0;
+  }
+}
+
+/* A disclosure panel opening and closing. Radix measures the panel and
+   publishes its height as --radix-accordion-content-height, so the panel
+   animates to its REAL height rather than to a guessed max-height — which is
+   what makes a long answer open at the same speed as a short one instead of
+   sitting still for half the duration. */
+@keyframes folio-accordion-down {
+  from {
+    height: 0;
+  }
+  to {
+    height: var(--radix-accordion-content-height);
+  }
+}
+
+@keyframes folio-accordion-up {
+  from {
+    height: var(--radix-accordion-content-height);
+  }
+  to {
+    height: 0;
+  }
+}
+
+/* The same idea for a lone disclosure. Radix publishes the measured height as
+   --radix-collapsible-content-height. */
+@keyframes folio-collapsible-down {
+  from {
+    height: 0;
+  }
+  to {
+    height: var(--radix-collapsible-content-height);
+  }
+}
+
+@keyframes folio-collapsible-up {
+  from {
+    height: var(--radix-collapsible-content-height);
+  }
+  to {
+    height: 0;
+  }
+}
+
+/* ─── Reduced motion ───
+   Two rules, and the argument behind them matters more than the CSS does.
+
+   This began as one opt-in rule: a surface that animated carried
+   `data-folio-animated`, and that attribute was what got cancelled. It was
+   forgotten four times — Accordion's panel, CollapsibleSection's panel,
+   SheetContent's slide, AppShell's drawer — by four authors across four
+   components. A mechanism four people independently fail to remember is not
+   being failed by its authors; it is failing them. The other half of the old
+   selector, `[class*='folio-anim']`, matched nothing whatsoever: Tailwind emits
+   `animate-[folio-collapsible-down_…]`, which contains no `folio-anim`, so half
+   the kill switch had never once fired and nothing anywhere said so.
+
+   So the GUARANTEE is now the universal rule below, deliberately the well-worn
+   one. It cannot be forgotten because there is nothing to remember: a new
+   component is covered before its author has heard of this file. It also
+   reaches `transition-duration`, which the old rule never did — and a panel
+   that slides is usually written as a transition, not a keyframe, which is how
+   two of the four escaped.
+
+   The cost, stated plainly: this is a `*` rule in a stylesheet consumers
+   import, so it reaches their components too. That is intended. It fires only
+   when the reader has asked their operating system for less motion, and this
+   package already asserts base styles on `*` (see index.css). A caller with
+   motion they consider essential can still keep it — `!important` on `*` is
+   the weakest `!important` there is, so any class-level
+   `animation-duration: … !important` outranks it. What changes is the default:
+   keeping motion under this preference becomes something you write down and
+   defend, instead of something you get by forgetting. That inversion is the
+   whole point of the change.
+
+   0.01ms rather than `none`, because JavaScript listens. Radix unmounts a
+   closing panel on `animationend`; consumer code may await `transitionend`. A
+   near-zero duration still fires both, where `none` fires neither. It is the
+   reset's least obvious detail and the reason it is written this way wherever
+   it appears.
+
+   `[data-folio-animated]` stays, and is no longer load-bearing. It is a
+   component asserting that its motion is decorative, and it goes further than
+   the floor above by removing the animation outright rather than running an
+   instant frame of it. Read it as documentation with teeth. Do NOT read it as
+   the thing that makes reduced motion work — believing that was the mistake
+   this replaced. `src/__tests__/reduced-motion.test.tsx` holds both ends: it
+   fails if this block stops being universal, if it stops naming transitions,
+   if it grows another selector that matches nothing, or if a component reaches
+   for a keyframe here without making the assertion. */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  ::before,
+  ::after {
+    animation-delay: 0ms !important;
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-delay: 0ms !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+
+  [data-folio-animated] {
+    animation: none !important;
+  }
+}

package/dist/lib/cn.d.ts

@@ -0,0 +1,21 @@
+import { ClassValue } from 'clsx';
+
+/**
+ * Join class names, and let the LAST one win.
+ *
+ * Every component in this package ends its class list with the caller's
+ * `className`, which is the only way an override is expressible. With plain
+ * `clsx` that override does not actually override: `clsx('px-6', 'px-2')` emits
+ * both, and which one applies is decided by the order Tailwind happened to emit
+ * the two utilities into the stylesheet — not by the call site. A caller
+ * tightening a button's padding therefore worked or did not depending on a
+ * detail neither side can see.
+ *
+ * `twMerge` resolves conflicts by utility GROUP, so `px-2` replaces `px-6`,
+ * `text-(--ink-2)` replaces `text-(--ink)`, and unrelated classes are left
+ * alone. Use this everywhere a caller's `className` is merged; `clsx` alone is
+ * still right for building a conditional list that no caller extends.
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+export { cn };

package/dist/lib/cn.js

@@ -0,0 +1,9 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+export {
+  cn
+};
+//# sourceMappingURL=cn.js.map

package/dist/lib/cn.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/cn.ts"],"sourcesContent":["import { clsx, type ClassValue } from 'clsx'\nimport { twMerge } from 'tailwind-merge'\n\n/**\n * Join class names, and let the LAST one win.\n *\n * Every component in this package ends its class list with the caller's\n * `className`, which is the only way an override is expressible. With plain\n * `clsx` that override does not actually override: `clsx('px-6', 'px-2')` emits\n * both, and which one applies is decided by the order Tailwind happened to emit\n * the two utilities into the stylesheet — not by the call site. A caller\n * tightening a button's padding therefore worked or did not depending on a\n * detail neither side can see.\n *\n * `twMerge` resolves conflicts by utility GROUP, so `px-2` replaces `px-6`,\n * `text-(--ink-2)` replaces `text-(--ink)`, and unrelated classes are left\n * alone. Use this everywhere a caller's `className` is merged; `clsx` alone is\n * still right for building a conditional list that no caller extends.\n */\nexport function cn(...inputs: ClassValue[]): string {\n  return twMerge(clsx(inputs))\n}\n"],"mappings":"AAAA,SAAS,YAA6B;AACtC,SAAS,eAAe;AAkBjB,SAAS,MAAM,QAA8B;AAClD,SAAO,QAAQ,KAAK,MAAM,CAAC;AAC7B;","names":[]}

package/dist/lib/color.d.ts

@@ -0,0 +1,80 @@
+/**
+ * CSS colour maths, with no dependency and no DOM.
+ *
+ * Adapted from DialKit (https://github.com/joshpuckett/dialkit), MIT licensed:
+ *
+ *   Copyright (c) 2026 Josh Puckett
+ *
+ *   Permission is hereby granted, free of charge, to any person obtaining a
+ *   copy of this software and associated documentation files (the "Software"),
+ *   to deal in the Software without restriction, including without limitation
+ *   the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ *   and/or sell copies of the Software, and to permit persons to whom the
+ *   Software is furnished to do so, subject to the following conditions:
+ *
+ *   The above copyright notice and this permission notice shall be included in
+ *   all copies or substantial portions of the Software.
+ *
+ * The working space is OKLCH, and that is the substantive choice here rather
+ * than an implementation detail. A picker built on HSV hands a reader two
+ * colours at the same "lightness" where one of them is visibly darker, because
+ * HSV's lightness is a property of the numbers rather than of the eye. Every
+ * decision in `ColorPicker` — where the handle sits, what the hue strip looks
+ * like at this lightness, which colours are reachable at all — depends on a
+ * space that is perceptually uniform, and OKLCH is the one CSS ships.
+ *
+ * The matrices are the CSS Color 4 reference implementation's, D65.
+ * https://www.w3.org/TR/css-color-4/#color-conversion-code
+ */
+/** A colour in OKLCH: lightness 0–1, chroma, hue in degrees, alpha 0–1. */
+interface Color {
+    l: number;
+    c: number;
+    h: number;
+    a: number;
+}
+/** The notations this module reads and writes. */
+type ColorFormat = 'hex' | 'oklch' | 'p3';
+/** The two RGB gamuts a colour can be fitted to. */
+type ColorSpace = 'srgb' | 'p3';
+type Triple = [number, number, number];
+declare const clamp: (n: number, min?: number, max?: number) => number;
+declare const wrapHue: (h: number) => number;
+/** Gamma-encoded RGB in 0–1 to OKLCH. */
+declare function rgbToColor(rgb: Triple, a?: number, space?: ColorSpace): Color;
+/** OKLCH to gamma-encoded RGB in 0–1. May fall outside it — see `fitGamut`. */
+declare function colorToRgb(color: Color, space?: ColorSpace): Triple;
+declare function inGamut(color: Color, space?: ColorSpace): boolean;
+/**
+ * Brings a colour inside a gamut by giving up CHROMA, and nothing else.
+ *
+ * The naive fix is to clip each channel at 0 and 1, which changes the hue and
+ * the lightness together — a vivid blue clipped that way comes back purple and
+ * darker. Bisecting on chroma keeps both, so what a reader loses is only the
+ * saturation the display could never have shown them.
+ */
+declare function fitGamut(color: Color, space?: ColorSpace): Color;
+/** The most chroma a gamut holds at this lightness and hue — the plane's edge. */
+declare function maxChroma(l: number, h: number, space?: ColorSpace): number;
+/** Which notation a string is written in. Anything unrecognised reads as hex. */
+declare function colorFormat(value: string): ColorFormat;
+/**
+ * A colour as a CSS string.
+ *
+ * Hex and Display P3 are bounded output spaces, so the colour is fitted on the
+ * way out; OKLCH is not, and writing an out-of-gamut OKLCH is legitimate — the
+ * browser fits it to whatever the display actually has.
+ */
+declare function formatColor(color: Color, format: ColorFormat): string;
+/**
+ * An absolute CSS colour as OKLCH, or `null` when the string is not one.
+ *
+ * Hex, `rgb()`, `hsl()`, `oklch()` and `color(display-p3 …)`, in both the
+ * comma and the space syntax. Named colours are deliberately absent: resolving
+ * them needs a table of a hundred and forty-eight entries or a DOM, and a
+ * picker that accepts "rebeccapurple" but not "papayawhip" is worse than one
+ * that accepts neither.
+ */
+declare function parseColor(value: string): Color | null;
+
+export { type Color, type ColorFormat, type ColorSpace, clamp, colorFormat, colorToRgb, fitGamut, formatColor, inGamut, maxChroma, parseColor, rgbToColor, wrapHue };