owoui

Reusable UI foundation components and default style preset.

Usage

import '@owodesign/owoui/style.css';
import { Button, Dialog, Select } from '@owodesign/owoui';

Example advanced primitives:

import {
  NavRail,
  Popover,
  RadioGroup,
  Table,
  Tree,
} from '@owodesign/owoui';

style.css is a compiled, publish-ready CSS asset. Consumers do not need Tailwind or a Tailwind PostCSS plugin to resolve it. It ships the component bundle together with theme-light + preset-default, so the full ref -> sys -> cmp token chain is present even when consumers only import one file.

To opt into another combination:

import '@owodesign/owoui/style.css';
import '@owodesign/owoui/theme-dark.css';
import '@owodesign/owoui/preset-glass.css';

Override order is intentional:

• style.css establishes the default baseline (theme-light + preset-default)
• later theme imports replace the theme layer
• later preset imports replace the preset layer

This package ships:

• reusable React UI primitives
• form primitives including Checkbox, Radio / RadioGroup, Select, SegmentedControl, Switch, Input, and Textarea
• structural primitives including Tree, NavRail, Table, Panel, Drawer, and SidePanel
• floating / feedback primitives including Popover, Tooltip, Dialog, and Toast
• a default style preset
• a standalone token stylesheet via @owodesign/owoui/tokens.css
• token metadata via @owodesign/owoui/tokens
• data-state hooks on complex components
• component-level customization surfaces for complex widgets
• a packaged storybook registry consumable via @owodesign/owoui/storybook
• a static storybook catalog consumable via @owodesign/owoui/storybook/catalog

Component Notes

• Checkbox exposes a stable three-state visual contract via data-state="unchecked" | "checked" | "indeterminate" on the root and control nodes.
• RadioGroup shares the ChoiceOption<T> model used by Select and SegmentedControl, supports orientation="vertical" | "horizontal" plus textValue for non-string labels, and exposes stable radio / radio-group part selectors.
• Popover uses a compound API: Popover.Root, Popover.Trigger, and Popover.Content. Popover.Content supports side, align, alignOffset, matchTriggerWidth, closeOnInteractOutside, closeOnEscape, closeOnPointerDownOutside, restoreFocus, initialFocusRef, onInteractOutside, onPointerDownOutside, and onEscapeKeyDown.
• Collapsible is the neutral disclosure primitive. Collapsible.Content defaults to unmountOnExit={true}, removes closed content from the tab order during collapse, and restores focus to the trigger if closing happens while a descendant is focused. CollapsiblePanel is the public styled layer and uses a compound Header / Title / Actions / Chevron / Content API. Settings / FAQ variants remain package-owned recipe patterns in Storybook rather than stable public exports.
• SidePanel is a layout component for left/right docked workbench panels rather than an overlay drawer. It supports controlled or uncontrolled collapse via collapsed, defaultCollapsed, and onCollapsedChange, built-in handle variants via handleVariant="tab" | "rail" with tab as the default, optional width resizing via resizable, width, defaultWidth, minWidth, maxWidth, and onWidthChange, opt-in width persistence via persistenceKey + persistenceMode="opt-in", viewport responsive behavior via responsiveMode + collapseBreakpoint, resize accessibility text via getResizeValueText, and workbench coordination hooks via layoutId, panelId, onResizeStart, onResizeEnd, onCollapseStart, and onCollapseEnd. It keeps a built-in collapse handle plus an optional dedicated resize handle, and exposes stable handle | resize-handle | panel | header | content part selectors.
• Tree now renders semantic nested treeitem -> group structure, uses dedicated expand controls instead of coupling row click with expansion, supports selectionMode="single" | "multiple" | "none", controlled selectedKeys, controlled expandedKeys, searchQuery filtering, and textValue for search on non-string labels.
• Tree exposes stable item | row | expander | expanderPlaceholder | content | label | description | meta | actions | group part selectors instead of the previous button-centric contract.
• NavRail provides NavRail.Item, NavRail.Section, and NavRail.Spacer for grouped icon-only navigation, plus orientation="vertical" | "horizontal" and arrow-key roving focus.
• Table supports selectionMode, controlled or uncontrolled sorting, sticky headers, fixed-row-height virtualization via virtualized, renderHeader, renderCell, compare, isRowSelectable, loading, loadingState, skeletonRows, classNames.row | rowSelected | headerCell | headerSortButton | headerLabel | cell | selectionCell | selectionControl | loadingState | skeletonCell, sortCycle, getSortButtonAriaLabel, getRowProps for safe row-level attribute/style/event injection with defensive merging, and rowComponent for constrained shell replacement (animation, drag-and-drop) with mandatory domProps/innerRef transparency.
• Select supports controlled value plus controlled popup state via open, defaultOpen, and onOpenChange.
• Table defaults to a documented binary sorting cycle on sortable columns: none -> asc -> desc -> asc. Set sortCycle="ternary" to enable none -> asc -> desc -> none.
• Table exposes onSortChange(sort) for explicit sort-state synchronization, including ternary clear-to-none transitions. Only sortable headers render an interactive button; static headers stay non-focusable.
• Table selection can be labeled explicitly through selectionColumnAriaLabel, getSelectAllAriaLabel, and getRowSelectionAriaLabel so standalone selection columns do not rely on implicit fallback copy.

Token Exports

For CSS-only token consumption:

import '@owodesign/owoui/tokens.css';

For programmatic token metadata:

import { tokenGroups, semanticTokenKeys, themeNames, presetNames } from '@owodesign/owoui/tokens';

Themes

• @owodesign/owoui/theme-light.css
• @owodesign/owoui/theme-dark.css

If you import theme-light.css after style.css, it is effectively a no-op because style.css already includes the same theme baseline.

Presets

• @owodesign/owoui/preset-default.css: Signature Look based on qblog's current default preset qualities
• @owodesign/owoui/preset-flat.css: low-depth preset with minimal shadows
• @owodesign/owoui/preset-elevated.css: stronger depth and larger radii
• @owodesign/owoui/preset-glass.css: translucent surfaces with blur

If you import preset-default.css after style.css, it is effectively a no-op because style.css already includes the default preset baseline.

There is no backward-compat alias layer for the previous dark.css / flat.css / elevated.css / glass.css entrypoints.

Storybook Artifact

owoui also ships a packaged storybook registry entry:

import { storybookStoryPaths, getStoriesByGroupAndComponent } from '@owodesign/owoui/storybook';

This is intended for host apps that want to mount the package stories under their own route shell.

For host apps that prefer a static navigation/catalog artifact, owoui also ships:

import storybookCatalog from '@owodesign/owoui/storybook/catalog';

It also builds a standalone static storybook site into dist/storybook-static/, which can be deployed directly or mounted by a host app as static files.

For package-local development with HMR, run:

npm run dev:storybook

The dev host lives inside this package itself (vite.config.ts, postcss.config.mjs, index.html) and does not depend on qblog's app shell.

Specs

• collapsible-layering-and-patterns.md: layering rules and official pattern boundaries for Collapsible, CollapsiblePanel, and package-owned settings / FAQ recipes
• form-control-boundaries.md: design and architecture boundaries for Field, Input, Textarea, and Select
• side-panel-layout-boundaries.md: long-term boundaries and public contract for the SidePanel layout component
• token-layering-and-naming.md: raw / alias / semantic token layering and naming rules
• token-naming-upgrade-plan.md: --owo-ref-* / --owo-sys-* / --owo-cmp-* naming migration plan

Pitches

• future-data-density-plan.md: phased proposal for control height tokens and future data-density support
• side-panel-handle-placement-implemented-2026-04.md: archived delivery record for the formal SidePanel handle placement contract
• virtual-list-industrial-design.md: proposal for introducing VirtualList as a dedicated primitive instead of merging virtualization into SidePanel
• side-panel-layout-component.md: implemented layout-side-panel design and delivery baseline
• side-panel-resizable-phase2.md: phase-2 review for whether SidePanel should gain a resizable width contract
• 03-side-panel-phase3-industrialization-implemented-2026-04.md: archived phase-3 delivery record for persistence, responsive behavior, advanced accessibility, and workbench-grade layout coordination

Release Checks

From the package root:

npm run release:check

After npm install, this repo also installs a local pre-push hook that runs the same verification chain before git push. If you need to bypass it for a one-off emergency push, use OWOUI_SKIP_PREPUSH=1 git push.

Publishing notes live in:

• PUBLISHING.md