@k8ordo/ui 2.0.0 → 2.2.0

package/dist/styles/utilities.css

@@ -1,62 +0,0 @@
-/**
- * Custom utilities.
- *
- * Imported by `index.css`. Part of the token source of truth —
- * run `pnpm generate:tokens` after editing.
- */
-
-@utility grid-cols-auto-fill-* {
-  grid-template-columns: repeat(
-    auto-fill,
-    minmax(min(calc(var(--spacing) * --value(integer)), 100%), 1fr)
-  );
-}
-
-@utility grid-cols-auto-fit-* {
-  grid-template-columns: repeat(
-    auto-fit,
-    minmax(min(calc(var(--spacing) * --value(integer)), 100%), 1fr)
-  );
-}
-
-@utility grid-rows-auto-fill-* {
-  grid-template-rows: repeat(
-    auto-fill,
-    minmax(min(calc(var(--spacing) * --value(integer)), 100%), 1fr)
-  );
-}
-
-@utility grid-rows-auto-fit-* {
-  grid-template-rows: repeat(
-    auto-fit,
-    minmax(min(calc(var(--spacing) * --value(integer)), 100%), 1fr)
-  );
-}
-
-@utility writing-h {
-  writing-mode: horizontal-tb;
-}
-
-@utility writing-v {
-  writing-mode: vertical-rl;
-  text-orientation: mixed;
-  text-underline-position: under left;
-  line-break: strict;
-  word-break: normal;
-}
-
-@utility writing-sideways-rl {
-  writing-mode: sideways-rl;
-}
-
-@utility z-overlay {
-  z-index: var(--z-overlay);
-}
-
-@utility z-modal {
-  z-index: var(--z-modal);
-}
-
-@utility z-toast {
-  z-index: var(--z-toast);
-}

package/docs/references/helpers.md

@@ -1,223 +0,0 @@
-# Helpers and types
-
-Utility functions and type definitions that `@k8ordo/ui` provides.
-
-```tsx
-import {
-  chain,
-  cn,
-  createSafeContext,
-  mergeProps,
-  mergeRefs,
-} from '@k8ordo/ui';
-import type {
-  Status,
-  Direction,
-  Placement,
-  ModalSide,
-  DrawerSide,
-  Option,
-} from '@k8ordo/ui';
-```
-
-The list below is the complete public helper API: `pnpm check:props` fails
-when the headings under "Helper functions" and the exports of
-`src/helpers/index.ts` disagree.
-
-## Helper functions
-
-### chain
-
-Combines several callbacks into one that calls each in order with the same
-arguments. `undefined` entries are skipped, so an optional user handler can be
-passed straight in. The combined function returns nothing.
-
-```tsx
-import { chain } from '@k8ordo/ui';
-
-const onClick = chain(props.onClick, () => {
-  setOpen(false);
-});
-
-<button onClick={onClick} />;
-```
-
-Signature:
-
-```ts
-const chain: <T extends (...args: never[]) => unknown>(
-  ...callbacks: Array<T | undefined>
-) => (...args: Parameters<T>) => void;
-```
-
-### cn
-
-Merges Tailwind classes (clsx + tailwind-merge). Accepts strings, arrays,
-objects, and falsy values, and resolves conflicting utilities with the last
-one winning.
-
-```tsx
-import { cn } from '@k8ordo/ui';
-
-cn('text-fg-base', isActive && 'bg-primary-bg', className);
-cn('flex', undefined, { hidden: false, grow: true }); // → 'flex grow'
-cn('px-4 py-2', 'px-6'); // → 'py-2 px-6'
-```
-
-Signature:
-
-```ts
-const cn: (...inputs: ClassValue[]) => string;
-```
-
-### createSafeContext
-
-Creates a context whose hook throws with the given message when there is no
-provider above it, instead of handing back `null`. Returns the context (to
-render as a provider) and the hook as a tuple.
-
-```tsx
-import { createSafeContext } from '@k8ordo/ui';
-
-const [TabsContext, useTabsContext] = createSafeContext<{
-  selectedId: string;
-}>('Tabs.Tab must be used within <Tabs.Root>');
-
-const Root = ({ children }) => (
-  <TabsContext value={{ selectedId }}>{children}</TabsContext>
-);
-
-const Tab = () => {
-  const { selectedId } = useTabsContext(); // throws outside <Root>
-};
-```
-
-Signature:
-
-```ts
-const createSafeContext: <T>(
-  errorMessage: string,
-) => readonly [Context<T | null>, () => T];
-```
-
-### mergeProps
-
-Merges two props objects the way a `render*` prop expects: `className` goes
-through `cn`, `style` is shallow-merged, event handlers (`onClick`,
-`onKeyDown`, …) are chained with `chain` so both run, and any other key is
-overwritten by `override` unless its value is `undefined`.
-
-```tsx
-import { mergeProps } from '@k8ordo/ui';
-
-const merged = mergeProps(
-  { className: 'p-2 text-fg-base', onClick: track },
-  { className: 'text-fg-mute', onClick: open, id: 'menu' },
-);
-// merged.className → 'p-2 text-fg-mute'
-// merged.onClick() → track(), then open()
-```
-
-Signature:
-
-```ts
-const mergeProps: <
-  A extends Record<string, unknown>,
-  B extends Record<string, unknown>,
->(
-  base: A,
-  override: B,
-) => Omit<A, keyof B> & B;
-```
-
-### mergeRefs
-
-Combines several refs into one callback ref, so a component can keep an
-internal ref while forwarding the caller's. Object refs are assigned, function
-refs are called, and `null` / `undefined` are skipped. The returned callback
-returns a cleanup (React 19 ref cleanup) that resets object refs to `null` and
-runs each function ref's own cleanup — or calls it with `null` when it did not
-return one.
-
-```tsx
-import { mergeRefs } from '@k8ordo/ui';
-
-const Field = ({ ref, ...rest }: { ref?: Ref<HTMLInputElement> }) => {
-  const internalRef = useRef<HTMLInputElement>(null);
-  return <input ref={mergeRefs(internalRef, ref)} {...rest} />;
-};
-```
-
-Signature:
-
-```ts
-const mergeRefs: <T>(
-  ...refs: ReadonlyArray<Ref<T> | undefined>
-) => RefCallback<T>;
-```
-
-## Type definitions
-
-### Status
-
-```tsx
-type Status = 'success' | 'info' | 'warning' | 'error';
-```
-
-Used for the status of Alert, Badge, Toast, and similar components.
-
-### Direction
-
-```tsx
-type Direction = 'up' | 'down' | 'right' | 'left';
-```
-
-Used to point ChevronIcon and similar icons.
-
-### Placement
-
-```tsx
-type Placement =
-  | 'top'
-  | 'top-start'
-  | 'top-end'
-  | 'bottom'
-  | 'bottom-start'
-  | 'bottom-end'
-  | 'left'
-  | 'left-start'
-  | 'left-end'
-  | 'right'
-  | 'right-start'
-  | 'right-end';
-```
-
-Placement relative to an anchor element, for Popover, Tooltip, DropdownMenu,
-and ListBox (the `placement` prop).
-
-### ModalSide
-
-```tsx
-type ModalSide = 'center' | 'bottom' | 'left' | 'right';
-```
-
-Which viewport edge a Modal sticks to (the `side` prop). It is a different
-idea from `Placement`, which is relative to an anchor, so the prop name differs
-too.
-
-### DrawerSide
-
-```tsx
-type DrawerSide = Extract<ModalSide, 'left' | 'right'>;
-```
-
-The subset of `ModalSide` a Drawer accepts: a drawer always slides in from an
-edge, so `center` is excluded.
-
-### Option
-
-```tsx
-type Option = Readonly<{ value: string; label: string }>;
-```
-
-Used for the choices in Radio, Select, Autocomplete, and similar components.

package/docs/references/hooks.md

@@ -1,301 +0,0 @@
-# Hooks
-
-The custom hooks `@k8ordo/ui` provides.
-
-```tsx
-import { useDisclosure, useDeferredDebounce } from '@k8ordo/ui';
-```
-
-These hooks cover UI mechanics: disclosure, timing, DOM observation, and the
-like. State that lives in a place — the URL, a history entry, localStorage,
-memory — is `@k8ordo/state`'s job (`defineLocalState` and friends). There is
-deliberately no `useLocalStorage`, `useSessionStorage`, or `useHash` here: a
-package that owned that state twice would give an app two answers.
-
-## State
-
-### useDisclosure
-
-Toggles open/closed state.
-
-```tsx
-const { isOpen, open, close, toggle } = useDisclosure();
-```
-
-### useControllableState
-
-Handles controlled and uncontrolled use transparently.
-
-```tsx
-const [value, setValue] = useControllableState({
-  value: controlledValue,
-  defaultValue: 'default',
-  onChange: onControlledChange,
-});
-```
-
-### useStep
-
-A step counter with forward/back control.
-
-```tsx
-const { count, next, back, isDisabledBack, isDisabledNext } = useStep({
-  initialCount: 0,
-  maxCount: 5,
-});
-```
-
-## Events
-
-### useClickAway
-
-Detects a click outside an element. Takes a ref and a callback.
-
-```tsx
-const ref = useRef<HTMLDivElement>(null);
-
-useClickAway(ref, (e) => {
-  console.log('clicked outside');
-});
-```
-
-Arguments:
-
-- `ref`: `RefObject<T | null>`
-- `callback`: `(e: Event) => void`
-- `enabled`: boolean (default: `true`)
-
-### useHover
-
-Detects the hover state. Spread `hoverProps` onto the element.
-
-```tsx
-const { isHovered, hoverProps } = useHover();
-
-<div {...hoverProps}>{isHovered ? 'hovered' : 'idle'}</div>;
-```
-
-`hoverProps` contains `{ onPointerEnter, onPointerLeave }`.
-
-## Timing
-
-> `useDeferredDebounce` and `useDebouncedTransition` do different jobs.
->
-> - **`useDeferredDebounce`**: **defers rendering**. The React scheduler simply postpones an expensive re-render; there is no guarantee about how long it waits. It cannot be used to throttle side effects (fetch, external APIs).
-> - **`useDebouncedTransition`**: **rate-limits side effects**. It waits for the given `delay` before running the action, and aborts the previous `AbortSignal` when called again. Use it for work you do not want fired in rapid succession, such as fetch.
-
-### useDeferredDebounce
-
-Wraps `useDeferredValue` and returns the value plus a pending flag for when it
-has not caught up. **For pure UI purposes only**, such as filtering a list as
-the user types.
-
-```tsx
-const [deferredValue, isPending] = useDeferredDebounce(inputValue);
-```
-
-Returns:
-
-- `[T, boolean]` — `[deferredValue, isPending]`
-
-### useDebouncedTransition
-
-Combines `startTransition(async)` with an `AbortController` and runs the action
-once the delay has elapsed. On a repeat call it aborts the signal passed to the
-previous action, so an `AbortError` thrown inside the action by, say,
-`fetch({ signal })` does not become an unhandled rejection.
-
-```tsx
-const [isPending, run] = useDebouncedTransition(300);
-
-const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
-  const q = e.target.value;
-  setQuery(q);
-  run(async (signal) => {
-    const res = await fetch(`/api/search?q=${q}`, { signal });
-    setResults(await res.json());
-  });
-};
-```
-
-Returns:
-
-- `[boolean, (action: (signal: AbortSignal) => void | Promise<void>) => void]`
-
-### useInterval
-
-Runs something on an interval.
-
-```tsx
-useInterval(() => {
-  fetchData();
-}, 5000);
-```
-
-### useTimeout
-
-Runs something after a delay.
-
-```tsx
-useTimeout(() => {
-  hideMessage();
-}, 3000);
-```
-
-## DOM and browser
-
-### useWindowSize
-
-Reads the window size.
-
-```tsx
-const { width, height } = useWindowSize();
-```
-
-### useWindowResize
-
-Listens for window resizes. The callback receives `{ width, height }`.
-
-```tsx
-useWindowResize(
-  (size) => {
-    recalculate(size.width, size.height);
-  },
-  { enabled: true },
-);
-```
-
-Arguments:
-
-- `callback`: `(size: { width: number; height: number }) => void`
-- `options`: `{ enabled?: boolean }`
-
-### useResize
-
-Observes an element's size (ResizeObserver). Takes a ref.
-
-```tsx
-const ref = useRef<HTMLDivElement>(null);
-
-useResize(
-  ref,
-  (entry) => {
-    console.log(entry.contentRect);
-  },
-  { enabled: true },
-);
-```
-
-Arguments:
-
-- `ref`: `RefObject<T | null>`
-- `callback`: `(entry: ResizeObserverEntry) => void`
-- `options`: `{ enabled?: boolean }`
-
-### useIntersectionObserver
-
-An intersection observer. Takes a ref.
-
-```tsx
-const ref = useRef<HTMLDivElement>(null);
-
-useIntersectionObserver(
-  ref,
-  (entry) => {
-    console.log(entry.isIntersecting);
-  },
-  { threshold: 0.5 },
-);
-```
-
-Arguments:
-
-- `ref`: `RefObject<T | null>`
-- `callback`: `(entry: IntersectionObserverEntry) => void`
-- `options`: IntersectionObserver options
-
-### useInView
-
-Whether an element is in view. Takes a ref and returns a boolean.
-
-```tsx
-const ref = useRef<HTMLDivElement>(null);
-const isInView = useInView(ref, { threshold: 0.1 });
-```
-
-Arguments:
-
-- `ref`: `RefObject<T | null>`
-- `options`: IntersectionObserver options
-
-### useScrollDirection
-
-Detects scroll direction, on both axes.
-
-```tsx
-const { x, y } = useScrollDirection();
-// x: 'left' | 'right'
-// y: 'up' | 'down'
-```
-
-### useScrollLock
-
-Locks scrolling on the body. Returns lock and unlock functions.
-
-```tsx
-const { lock, unlock } = useScrollLock();
-
-// when opening a modal
-lock();
-
-// when closing it
-unlock();
-```
-
-### useWritingMode
-
-Detects an element's `writing-mode` and returns `'horizontal'` or `'vertical'`.
-Every `vertical-*` and `sideways-*` value normalizes to `'vertical'`. It
-observes through a ResizeObserver, and returns `'horizontal'` during SSR.
-
-```tsx
-const ref = useRef<HTMLDivElement>(null);
-const writingMode = useWritingMode(ref); // 'horizontal' | 'vertical'
-```
-
-Arguments:
-
-- `ref`: `RefObject<Element | null>`
-
-Returns:
-
-- `'horizontal' | 'vertical'`
-
-### useBreakpoint
-
-Tests a Tailwind breakpoint.
-
-```tsx
-const isMd = useBreakpoint('md'); // whether the viewport is 768px or wider
-```
-
-## Utilities
-
-### useClient
-
-Whether we are on the client.
-
-```tsx
-const isClient = useClient();
-```
-
-### useClipboard
-
-Reads from and writes to the clipboard.
-
-```tsx
-const { writeClipboard, readClipboard } = useClipboard();
-
-await writeClipboard('the text to copy');
-const text = await readClipboard();
-```