@povio/ui 5.0.0-rc.1 → 5.0.0-rc.2

package/.rulesync/rules/ui-buttons-and-content.md

@@ -0,0 +1,54 @@
+---
+targets: ["*"]
+description: "@povio/ui buttons, labels, status feedback, and text-content APIs"
+globs:
+  - "packages/ui/src/components/buttons/**/*"
+  - "packages/ui/src/components/text/**/*"
+  - "packages/ui/src/components/status/**/*"
+  - "packages/ui/src/components/shared/pagination/**/*"
+---
+
+# Buttons, text, and status components
+
+## Button
+
+Use `Button` for an action. Its content is `children`; use `link` only when it navigates through the configured `LinkContext`.
+
+- Visual variants: `contained`, `solid`, `outlined`, `outline`, `subtle`, `text`, `ghost`. The default CVA styles `solid` like `contained` and `outline` like `outlined`, but passes every value through unchanged so UI overrides can redefine either value.
+- Colors: `primary`, `secondary`, `error` (destructive theme tokens), and Atlas-specific `dual`. Text buttons with `dual` use primary text and secondary icons. Only primary text buttons support `inverted`, using the primary foreground token.
+- Sizes: `sm` (alias `s`), `default`, and `none` (zero padding); omit the size prop for `default`. Legacy sizes (`xs`, `small`, `m`, `md`, `l`, `lg`) are not supported.
+- Use `fullWidth`; `width="fill"` and `width="hug"` remain valid.
+- Use `loading` or `isLoading`; loading disables the button by default. `disableWhileLoading={false}` opts out; `noDisableWhenLoading` is the legacy inverse.
+- Use `startIcon` and `endIcon`. `icon` plus `iconPosition="left" | "right"` remains supported.
+- Use `IconButton` for icon-only actions and supply `ariaLabel` or `label`. `InlineIconButton` is the text-style icon-only variant.
+- Use `ToggleButton` for one independently toggled state (`isSelected`, `defaultSelected`, `onChange`). It defaults to outlined primary but honors supplied `variant` and `color`.
+- Use `SplitButton` only for a primary action with menu alternatives; use `ButtonGroup` for peer actions.
+- `variant`, `size`, and other CVA props belong to the active override. Never normalize their values inside a component; define default compatibility aliases as CVA entries instead.
+- `PillButton` has its own CVA but follows the same variant contract: `solid` and `outline` are default aliases and are passed unchanged to `pillButton.cva` overrides.
+
+## Tags, links, typography
+
+Typography sizes are `headline-l`, `h1`–`h4`, `lead`, `body`, `large`, and `small`; There is no typography `variant`; use `className="font-bold"` or `className="italic"` for emphasis. `large` and `small` do not add font weight; use explicit emphasis when needed. Use the same size on mobile and desktop unless explicitly overridden.
+
+- `Badge` and `Tag` are display components, not generic buttons. Use `dismissible` and `onRemove` for removal; `dismissable` and `onDismiss` are legacy forms.
+- Pass remove-button behavior through `dismissButtonProps`; arbitrary button props do not belong on the display container.
+- Use `Link` for navigation and `Button` for actions.
+- Use `Typography` with semantic `as` elements (`h1`, `h2`, `p`, `span`) and library typography variants/sizes. Token changes belong in UI overrides, not consumers.
+
+## Feedback
+
+- Use `Alert` for persistent inline status, `Toast`/`useToast` for transient notifications, `Spinner` for indeterminate progress, and `Progress` for numeric progress.
+- For alerts and toasts, keep `variant` (`contained`/`outlined`) separate from semantic `color` (`neutral`, `success`, `warning`, `error`).
+- Toast actions are `{ text, onPress }`; keep them short and non-destructive.
+
+## Reference
+
+- `packages/ui/src/components/buttons/Button/Button.tsx` — Button behavior and compatibility.
+- `packages/ui/src/components/text/Tag/Tag.tsx` — dismissible tag contract.
+- `packages/ui/src/components/status/Toast/Toast.tsx` — toast content and actions.
+
+## When refactoring
+
+- `Button` uses `icon` only for a conventional start/end icon → use `startIcon` or `endIcon`.
+- An icon-only action has no accessible name → use `IconButton` with `ariaLabel` or `label`.
+- A tag/pill receives `onPress` to represent selection → use `ToggleButton` or `ToggleGroup`.

package/.rulesync/rules/ui-inputs-and-forms.md

@@ -0,0 +1,62 @@
+---
+targets: ["*"]
+description: "@povio/ui form fields, selection controls, pickers, uploads, and React Hook Form integration"
+globs:
+  - "packages/ui/src/components/inputs/**/*"
+  - "packages/ui/src/hooks/useForm*.ts"
+---
+
+# Inputs and forms
+
+## Shared field contract
+
+- Sizes: `small` and `default` only. Omit `size` for the default; `extra-small` and `large` are not supported. This shared input API has no `sm` or `s` aliases.
+- Use `label`, `helperText`, `error`, `isRequired`, and `isDisabled` as the base field contract.
+- `Input`, `TextArea`, and `NumberField` also accept `errorMessage`, `required`, and `disabled`. Their visual layout is `layout="default" | "floating" | "filter" | "inline"`; `as` remains the legacy layout prop and is not polymorphic element selection.
+- Use `variant="outlined" | "filled"` for text-like inputs. Keep layout separate from variant.
+- Use `isClearable`, `leadingIcon`, `trailingIcon`, `action`, `unit`, `placeholder`, and `inputClassName` only where exposed; do not recreate input chrome in consumers.
+- Controlled fields use `value` and `onChange`; uncontrolled fields use `defaultValue`. Preserve callback value types: strings for text, `number | null` for number fields, and component-specific date values for pickers.
+
+## Selection controls
+
+- `Checkbox` uses `isSelected`, `defaultSelected`, and `onChange(boolean)`; `children` may be any `ReactNode`.
+- `Switch` uses the same boolean selection contract.
+- `RadioGroup` takes `options: { label, value }[]` and scalar `value`/`defaultValue`/`onChange`.
+- `CheckboxGroup` takes the same options shape and array values. `allValue` is an Atlas extension for all-selected representation.
+- `ToggleGroup`, `Select`, and `Autocomplete` use `selectionMode="single" | "multiple"`. Single values are `Key | null`; multiple values are `Key[]`.
+- `Select` is a closed selection field. `Autocomplete` is the searchable/combobox form of the same item API. Both take `items: { id, label, content?, isDisabled? }[]`.
+- Preserve Select capabilities: `isSearchable`, `isClearable`, `showSelectAllOption`, `showSelectionBar`, `showNewItemOption`, `onNewItemOption`, async `isLoading`/`hasLoadMore`/`onLoadMore`, and `virtualizerOptions`.
+- Use `QuerySelect` and `QueryAutocomplete` only with the package TanStack Query adapter; they are not generic async-select replacements.
+
+## Dates, ranges, files, rich text
+
+- Use `DatePicker`, `DateRangePicker`, `TimePicker`, and `DateTimePicker` for React Aria date values. Preserve `minValue`, `maxValue`, `granularity`, `isClearable`, and date-input options rather than replacing them with native inputs.
+- Use `Slider` with numeric `value`/`defaultValue`; set `isRange` for two-thumb values.
+- Use `FileInput` for controlled form file values and `FileUpload` for upload lifecycle, progress, cancellation, and uploaded-file display. Both accept `multiple` or `allowsMultiple`.
+- Import `RichTextEditor` from `@povio/ui/rich-text-editor`, not the main package entry point.
+
+## Forms
+
+```tsx
+// TanStack Form (native binding, e.g. import from "@povio/ui/tanstack/input")
+<Input label="Name" field={{ form, name: "name" }} />
+
+// React Hook Form (adapter, e.g. import from "@povio/ui/rhf/input")
+<Input label="Name" formControl={{ control: form.control, name: "name" }} />
+```
+
+- `field` (TanStack) and `formControl` (React Hook Form) each own `value`, `onChange`, and `onBlur`; do not supply competing controlled props alongside either.
+- `Form` and `Inputs` are Zod schema helpers, available in both the TanStack-native and React Hook Form flavors. Use a regular HTML `<form>` with individual fields when schema-generated rendering is not needed.
+
+## Reference
+
+- `packages/ui/src/components/inputs/Input/Input.tsx` — core text-field API.
+- `packages/ui/src/components/inputs/Selection/shared/SelectBase.tsx` — selection and async capabilities.
+- `packages/ui/src/components/inputs/shared/form.types.ts` — typed `field` (TanStack) contract.
+- `packages/ui/src/rhf/form.types.ts` — typed `formControl` (React Hook Form) contract.
+
+## When refactoring
+
+- A consumer uses `as` to select a DOM element → use `layout`; `as` controls legacy input presentation.
+- App code checks `allowsMultiple` → prefer `multiple` in new code.
+- A select hand-rolls filtering or virtualized results → use the exposed Select/Autocomplete props before adding consumer-side overlay logic.

package/.rulesync/rules/ui-overlays-navigation-and-styling.md

@@ -0,0 +1,49 @@
+---
+targets: ["*"]
+description: "@povio/ui overlays, navigation, tables, accessibility, and styling conventions"
+globs:
+  - "packages/ui/src/components/overlays/**/*"
+  - "packages/ui/src/components/navigation/**/*"
+  - "packages/ui/src/components/DropdownMenu/**/*"
+  - "packages/ui/src/components/Breadcrumbs/**/*"
+  - "packages/ui/src/components/table/**/*"
+  - "packages/ui/src/components/**/*.cva.ts"
+---
+
+# Overlays, navigation, tables, and styling
+
+## Overlays and navigation
+
+- Use `Dialog` with controlled `isOpen`; handle transitions with `onOpenChange`. `onClose` remains available for close-only behavior.
+- Use `AlertDialog` for confirmations with a primary action and optional secondary action.
+- Use `Drawer` for a side panel and `BottomSheet` for a mobile bottom sheet. Both own focus trapping and dismissal; do not mount parallel ad-hoc overlays.
+- `Popover` renders a desktop popover and mobile bottom sheet. It requires a trigger, controlled state, and accessible `sheetLabel`.
+- Use `Tooltip` for supplemental text only; it must not be the sole accessible label for an icon action.
+- Use `DropdownMenu` with `trigger`, `items`, and `onAction`. Menu items are `{ id, label, content?, link?, children? }`; nested `children` create submenus.
+- Use `Accordion` for expandable content, `Stepper` for step progress, `Breadcrumbs` for hierarchy, and `Pagination`/`PaginationList` for page navigation.
+
+## Tables
+
+- `Table` is the base TanStack wrapper. Use `PaginatedTable` or `InfiniteTable` only when their data-loading contracts match the view.
+- Keep table columns in the consumer domain. Use `CellText` and `HeaderText` for consistent text treatment; use `ColumnConfigModal` for persisted visibility/configuration behavior.
+
+## Styling and accessibility
+
+- Components use class-variance-authority, `UIOverrides`, and tokenized Tailwind classes. Add visual variants through the relevant `*.cva.ts` definition and expose a typed variant prop; do not add hard-coded color values in consumers.
+- Use `UIConfig` for package-wide defaults and `UIOverrides` for recipe overrides. Do not duplicate component markup to bypass them.
+- Preserve React Aria state props/data attributes (`isDisabled`, `isSelected`, `isInvalid`, `data-selected`) when wrapping controls.
+- Root styling uses `className`. Prefer existing slot props (`inputClassName`, `dialogClassName`, `overlayClassName`, `containerClassName`) over selectors reaching into library internals.
+- Keep button-like controls keyboard accessible. Icon-only actions need an accessible name; labels remain associated with fields.
+- Avoid nested runtime ternaries in rendering or prop normalization. Use a named helper, map, or explicit branch.
+
+## Reference
+
+- `packages/ui/src/components/overlays/Dialog/Dialog.tsx` — controlled dialog behavior.
+- `packages/ui/src/components/DropdownMenu/DropdownMenu.tsx` — responsive menu boundary.
+- `packages/ui/src/config/uiOverrides.context.tsx` — recipe override system.
+
+## When refactoring
+
+- A component hard-codes a visual token already represented by a CVA recipe → add or reuse a typed recipe variant.
+- An icon-only trigger relies only on a tooltip → add an `aria-label`/`ariaLabel` or visible label.
+- Overlay state is duplicated in an app wrapper and a UI component → make controlled `isOpen`/`onOpenChange` the source of truth.

package/.rulesync/rules/ui-overview.md

@@ -0,0 +1,33 @@
+---
+root: true
+targets: ["*"]
+description: "@povio/ui public API and component-selection guidance"
+globs: ["packages/ui/**/*"]
+---
+
+# @povio/ui component-library overview
+
+`@povio/ui` is a React 19, TypeScript, Tailwind 4 component library built on React Aria Components. Import components and hooks from component-scoped subpaths (e.g. `@povio/ui/dialog`, `@povio/ui/rich-text-editor`), or from the broader `@povio/ui/rhf` (React Hook Form) or `@povio/ui/tanstack` (TanStack Form) entries; internal `src/components/**` paths are not consumer APIs.
+
+## Public API and naming
+
+- `src/rhf.ts` and `src/tanstack.ts` are the authoritative barrels for the two form-integration flavors; `src/entries/*.ts` (plus `src/entries/rhf/*.ts` and `src/entries/tanstack/*.ts` for form-capable components) back the individual `package.json#exports` subpaths. Add or change a public component in all three places together with its prop type.
+- Component names are canonical and final: `Input`, `NumberField`, `FileInput`, `Switch`, `ToggleGroup`, `DropdownMenu`, `Dialog`, `AlertDialog`, `Popover`, `Spinner`, `Progress`, `Badge`, `RichTextEditor` (exported from `@povio/ui/rich-text-editor`).
+- Use `ButtonGroup` for grouped independent actions. Use `ToggleGroup` only when the group represents selected value(s).
+
+## Common conventions
+
+- Components use React Aria event names (`onPress`, `onChange`, `isDisabled`, `isSelected`) as their base API.
+- Form-capable components speak a native `field: { form, name }` TanStack Form binding. Consumers on `@povio/ui/rhf/*` get the same components wrapped with a `formControl: { control, name }` React Hook Form adapter instead. Do not pass `value`, `onChange`, or `onBlur` together with `field`/`formControl`.
+- Keep public props semantic and domain-independent. Use `className` for root styling and component-specific `*ClassName` props only for independently styled internal slots.
+- Prefer `ReactNode` for display content and preserve `aria-*` props through to the interactive element.
+
+## Reference
+
+- `packages/ui/src/rhf.ts` / `packages/ui/src/tanstack.ts` — public exports per form-integration flavor.
+- `packages/ui/src/config/uiConfig.context.tsx` — runtime component defaults.
+
+## When refactoring
+
+- A consumer imports from `src/components/...` → switch it to a package subpath export.
+- A stateful segmented control is used as an action toolbar → use `ButtonGroup` and `Button`s instead.

package/README.md

@@ -62,21 +62,15 @@ Replace `size="extra-small"` with `size="small"`, and remove `size="large"` or `
 
 The package ships RuleSync source rules in `.rulesync/` and `rulesync.jsonc`. They document the public component API, standard aliases, form contracts, accessibility expectations, and styling conventions for AI coding tools. Generated tool files are deliberately excluded from the published npm package.
 
-To generate the UI rules into a consuming project's repository root, run the executable bundled with `@povio/ui`:
+To generate the UI rules into a consuming project's repository root, install [`rulesync`](https://github.com/dyoshikawa/rulesync) (`^8.15.0`) in that project, then run the executable bundled with `@povio/ui`:
 
 ```bash
-pnpm exec povio-ui-rules
+bunx --package @povio/ui povio-ui-rules
 ```
 
-With npm, use:
+This generates the relevant Cursor, Claude Code, and Codex CLI files in the consuming repository. Add generated files to that repository's `.gitignore` unless they are intentionally versioned. Re-run the command after upgrading `@povio/ui`; verify without writing files by adding `--check` (for example, `bunx --package @povio/ui povio-ui-rules --check`).
 
-```bash
-npx povio-ui-rules
-```
-
-This generates the relevant Cursor, Claude Code, and Codex CLI files in the consuming repository. Add generated files to that repository's `.gitignore` unless they are intentionally versioned. Re-run the command after upgrading `@povio/ui`; verify without writing files by adding `--check` (for example, `pnpm exec povio-ui-rules --check`).
-
-Within this monorepo, the equivalent package-local commands are `pnpm --filter @povio/ui rules:gen` and `pnpm --filter @povio/ui rules:check`.
+Within this monorepo, the equivalent package-local commands are `bun run --filter @povio/ui rules:gen` and `bun run --filter @povio/ui rules:check`.
 
 ## Publishing
 

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@povio/ui",
-  "version": "5.0.0-rc.1",
+  "version": "5.0.0-rc.2",
   "type": "module",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "povio-ui-rules": "./scripts/generate-rules.mjs"
+  },
   "sideEffects": [
     "**/*.css"
   ],
@@ -1313,7 +1316,10 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "scripts/generate-rules.mjs",
+    ".rulesync",
+    "rulesync.jsonc"
   ],
   "homepage": "https://povio.com",
   "license": "UNLICENSED",

package/rulesync.jsonc

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/config-schema.json",
+  "targets": ["cursor", "claudecode", "codexcli"],
+  "features": ["rules"],
+  "outputRoots": ["."],
+  "delete": true,
+  "verbose": false,
+  "silent": false,
+  "global": false,
+  "gitignoreTargetsOnly": true,
+}

package/scripts/generate-rules.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const rulesyncEntry = require.resolve("rulesync");
+const rulesyncCli = join(dirname(rulesyncEntry), "cli", "index.js");
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const configPath = join(packageRoot, "rulesync.jsonc");
+
+const result = spawnSync(
+  process.execPath,
+  [
+    rulesyncCli,
+    "generate",
+    "--input-root",
+    packageRoot,
+    "--config",
+    configPath,
+    "--output-roots",
+    process.cwd(),
+    ...process.argv.slice(2),
+  ],
+  { stdio: "inherit" },
+);
+
+if (result.error) {
+  throw result.error;
+}
+
+process.exitCode = result.status ?? 1;