prime-ui-kit 0.9.0 → 0.9.2

package/src/components/hint/COMPONENT.md

@@ -1,15 +1,16 @@
 # Hint
 
 **Category:** inputs
+**Kind:** primitive
 
 > Help text or a validation error under a field.
 
 ## When to use
-- Under a control without `hint`/`error` props (DigitInput, ColorPicker, a custom control) or a hand-built field where you wire the ids yourself: format rules, limits, where the value comes from.
-- As the error message of such a field (`invalid`), in the same slot as the hint.
+- Under a control without `hint` / `error` props (SegmentedControl, Slider, a custom control) where you wire the ids yourself: format rules, limits, where the value comes from.
+- As the error message of such a control (`invalid`), in the same slot as the hint.
 
 ## When not to use
-- Input, Textarea, Checkbox and other fields with `hint` / `error` props → pass the props; they render Hint and link the ids ([Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md)).
+- Input, Textarea, Select, Checkbox and other fields with `hint` / `error` props → pass the props; they render Hint and link the ids ([Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md)).
 - The field name → use [Label](../label/COMPONENT.md).
 - A message about the whole page or form (success, warning) → use [Banner](../banner/COMPONENT.md) or a [Notification](../notification/COMPONENT.md).
 - An explanation on hover → use [Tooltip](../tooltip/COMPONENT.md).
@@ -22,29 +23,25 @@ import { Hint } from "prime-ui-kit";
 ## Anatomy
 ```
 Hint.Root      <p> with the text
-└─ Hint.Icon   optional leading icon, centered on the first line (aria-hidden)
+└─ Hint.Icon   optional leading icon, centred on the first line (aria-hidden)
 ```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### Hint.Root
-No ref. + native `<p>` props (`id`, `role`, `className`, …).
+`ref` → `HTMLParagraphElement`. A `<p>` with the support text; provides its tier to nested icons. + native `<p>` props (`id`, `role`, `className`, …).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Size of the paired field: xs/s/m 12/16 · l/xl 13/20. Also provided to nested icons via the control-size context. |
-| `invalid` | `boolean` | — | Error message styling: danger text. |
-| `disabled` | `boolean` | — | Disabled text color, next to a disabled control. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the paired field: 12/16 for xs–m, 13/20 for l and xl. |
+| `invalid` | `boolean` | `false` | Error styling: danger text that drops in (fade + 4 px from above). |
+| `disabled` | `boolean` | `false` | Disabled text color, next to a disabled control. |
 | `children` | `ReactNode` | — | Text, optionally with `Hint.Icon` first. |
-| `className` | `string` | — | Class on the `<p>`. |
 
 ### Hint.Icon
-No ref. + native `<span>` props. Always `aria-hidden`.
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `children` | `ReactNode` | — (required) | An icon; drawn at 14px for xs/s/m and 16px for l/xl, centered on the first line. |
-| `className` | `string` | — | Class on the `<span>`. |
+`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` holding a glyph: 14 px for xs–m, 16 px for l and xl, centred on the first line. + native `<span>` props.
 
 ## Variants
 Hint has no `variant` or `tone`; its states are flags.
@@ -52,61 +49,58 @@ Hint has no `variant` or `tone`; its states are flags.
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | 12/16, muted | Under an `xs` field | |
-| `s` | 12/16, muted | Under an `s` field | |
+| `xs` | 12/16, muted, icon 14 | Under an `xs` field | |
+| `s` | 12/16, muted, icon 14 | Under an `s` field | |
 | `m` | 12/16, muted, icon 14 | Under an `m` field | yes |
 | `l` | 13/20, muted, icon 16 | Under an `l` field | |
 | `xl` | 13/20, muted, icon 16 | Under an `xl` field | |
 
-**Sizes:** the hint is always smaller than the field text; use the field's size.
+The hint is always smaller than the field text; use the field's size.
 
-### State flags
-| Flag | Looks like | Use when | Default |
+### Flags
+| Value | Looks like | Use when | Default |
 |---|---|---|---|
-| — (none) | Muted text, caption tracking | Help, format, limits | yes |
-| `invalid` | Danger text | Validation error | — |
-| `disabled` | Disabled text | Under a disabled control | — |
+| `invalid` | Danger text, drops in | Validation error | `false` |
+| `disabled` | Disabled text | Under a disabled control | `false` |
 
-**Combinations**
-- Recommended: one element that switches between hint text and error text with `invalid` (no layout jump); `role="alert"` for errors shown after a user action.
-- Pointless: `invalid` and `disabled` together.
-- There is no success state: use neutral text, or a [Banner](../banner/COMPONENT.md) for a result.
+**Combinations** — one element switches between the hint text and the error text with `invalid` (no layout jump); add `role="alert"` to an error shown after a user action. `invalid` and `disabled` together make no sense. There is no success state: use neutral text, or a [Banner](../banner/COMPONENT.md) for a result.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| error | `invalid` | `data-invalid="true"` |
+| error | `invalid` | `data-invalid="true"`; the message drops in over `fast` (fade + `--prime-space-1` from above, no shake, no layout shift) and the color eases from the hint color |
 | disabled | `disabled` | `data-disabled="true"` |
 | size | `size` | `data-size` |
 
 Hint is not interactive: hover and focus belong to the field.
 
 ## Layout & spacing
-- Field → hint: the tier `hint-gap` (`--prime-control-<size>-hint-gap` = `--prime-space-1`), set by the field layout, not by Hint.
-- Hint → icon gap: `--prime-space-1`. Long text wraps (`overflow-wrap: anywhere`).
+- Field → hint: the tier `hint-gap` (`--prime-control-<size>-hint-gap`), set by the field layout, not by Hint.
+- Icon → text gap: `--prime-space-1`. Long text wraps (`overflow-wrap: anywhere`).
 
 ## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
 - Give the hint an `id` and put it into the control's `aria-describedby` so screen readers read it with the field.
 - Add `role="alert"` to an error that appears after a user action.
-- `Hint.Icon` is decorative; the text must carry the meaning.
-- Hint has no `labels`.
+- `Hint.Icon` is decorative; the text carries the meaning.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [sizes.tsx](examples/sizes.tsx) | `xs`…`xl` | Matching the field size |
-| [states.tsx](examples/states.tsx) | Default, `invalid`, `disabled`, with `Hint.Icon` | Picking the message style |
-| [field-states.tsx](examples/field-states.tsx) | Label + Select + Hint with `aria-describedby` in default / error / disabled | Hand-built fields |
-| [hint-or-error.tsx](examples/hint-or-error.tsx) | Toggling `invalid` and text in the same element with `role="alert"` | Validation after an action |
-| [in-form.tsx](examples/in-form.tsx) | Password change form using the Input `hint` / `error` props | Fields that have hint props |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-```tsx
-import { Hint } from "prime-ui-kit";
+No `labels`.
 
-export function PhoneHint() {
-  return <Hint.Root id="phone-hint">Формат: +7 900 000-00-00</Hint.Root>;
-}
-```
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Help text under a control without its own `hint` prop, linked to it by `id` and `aria-describedby`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier, matching the field above: 12/16 for xs–m, 13/20 for l and xl — `size`. |
+| [states.tsx](examples/states.tsx) | Default help text next to an error and a hint under a disabled control — `invalid`, `disabled`. |
+| [with-icon.tsx](examples/with-icon.tsx) | A leading icon centred on the first line, in the default and the error state — `Hint.Icon`. |
+| [hint-or-error.tsx](examples/hint-or-error.tsx) | After a check the error replaces the hint in the same element, without a layout jump, and is announced — `invalid`, `role`. |
 
 ## Mistakes
 - `<Hint.Root>` under an Input → use `hint` / `error` on `Input.Root`; it links the ids itself.
@@ -115,5 +109,5 @@ export function PhoneHint() {
 - Hint size different from the field size → use the same `size`.
 
 ## Related
-- [Label](../label/COMPONENT.md) — the field name above.
-- [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [DigitInput](../digit-input/COMPONENT.md), [Select](../select/COMPONENT.md).
+- **Built from:** —
+- **See also:** [Label](../label/COMPONENT.md), [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/hint/examples/examples.module.css

@@ -1,41 +1,9 @@
-/* Layout helpers for the Hint examples. Semantic tokens only. */
-
-.sizes {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: flex-end;
-  justify-content: center;
-  gap: var(--prime-space-8);
-}
-
-.sizeCell {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-2);
-}
-
-.list {
-  display: grid;
-  justify-items: start;
-  gap: var(--prime-space-3);
-}
-
-.fields {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--prime-panel-min-width)), 1fr));
-  gap: var(--prime-space-5);
-  width: 100%;
-}
+/* Layout of the Hint scenarios: semantic tokens only. */
 
+/* overview.tsx, hint-or-error.tsx: label → control → support row with the m-tier gaps. */
 .field {
   display: grid;
-  align-content: start;
-  gap: var(--prime-control-m-label-gap);
-}
-
-.fieldBody {
-  display: grid;
+  justify-items: start;
   gap: var(--prime-control-m-hint-gap);
 }
 
@@ -44,13 +12,3 @@
   flex-wrap: wrap;
   gap: var(--prime-space-2);
 }
-
-.form {
-  display: grid;
-  gap: var(--prime-space-5);
-  width: 100%;
-  max-width: var(--prime-modal-width-s);
-  padding: var(--prime-card-padding-m);
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-card-bg);
-}

package/src/components/hint/examples/hint-or-error.tsx

@@ -1,4 +1,4 @@
-/** The parent toggles `invalid` and the text of the same element, so the error replaces the hint without a layout jump; `role="alert"` announces it. Use it for validation after a user action. */
+/** After a check the error replaces the hint in the same element, without a layout jump, and is announced — `invalid`, `role`. */
 import { Button, Hint } from "prime-ui-kit";
 import * as React from "react";
 
@@ -8,12 +8,12 @@ export default function HintHintOrErrorExample() {
   const [invalid, setInvalid] = React.useState(false);
 
   return (
-    <div className={styles.list}>
+    <div className={styles.field}>
       <div className={styles.actions}>
-        <Button.Root variant="outline" tone="neutral" size="s" onClick={() => setInvalid(true)}>
-          Проверить
+        <Button.Root variant="soft" tone="neutral" onClick={() => setInvalid(true)}>
+          Опубликовать
         </Button.Root>
-        <Button.Root variant="ghost" tone="neutral" size="s" onClick={() => setInvalid(false)}>
+        <Button.Root variant="ghost" tone="neutral" onClick={() => setInvalid(false)}>
           Сбросить
         </Button.Root>
       </div>

package/src/components/hint/examples/overview.tsx

@@ -0,0 +1,34 @@
+/** Help text under a control without its own `hint` prop, linked to it by `id` and `aria-describedby`. */
+import { Hint, Label, SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PERIODS = [
+  { value: "day", label: "День" },
+  { value: "week", label: "Неделя" },
+  { value: "month", label: "Месяц" },
+];
+
+export default function HintOverviewExample() {
+  const labelId = React.useId();
+  const hintId = React.useId();
+
+  return (
+    <div className={styles.field}>
+      <Label.Root id={labelId}>Период отчёта</Label.Root>
+      <SegmentedControl.Root
+        defaultValue="week"
+        aria-labelledby={labelId}
+        aria-describedby={hintId}
+      >
+        {PERIODS.map((period) => (
+          <SegmentedControl.Item key={period.value} value={period.value}>
+            {period.label}
+          </SegmentedControl.Item>
+        ))}
+      </SegmentedControl.Root>
+      <Hint.Root id={hintId}>Отчёт пересчитывается каждую ночь в 03:00 по Москве.</Hint.Root>
+    </div>
+  );
+}

package/src/components/hint/examples/sizes.tsx

@@ -1,19 +1,17 @@
-/** Hint sizes match the paired field: xs/s/m 12/16 · l/xl 13/20, always smaller than the field text. Use the size of the field above. */
-import { type ControlSize, Hint, Typography } from "prime-ui-kit";
+/** Every size tier, matching the field above: 12/16 for xs–m, 13/20 for l and xl — `size`. */
+import { Hint, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
-const sizes: ControlSize[] = ["xs", "s", "m", "l", "xl"];
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function HintSizesExample() {
   return (
-    <div className={styles.sizes}>
-      {sizes.map((size) => (
-        <div key={size} className={styles.sizeCell}>
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
           <Hint.Root size={size}>Не менее 8 символов</Hint.Root>
-          <Typography.Root as="span" variant="caption" tone="muted">
+          <Typography as="span" variant="caption" tone="muted">
             {size}
-          </Typography.Root>
+          </Typography>
         </div>
       ))}
     </div>

package/src/components/hint/examples/states.tsx

@@ -1,20 +1,27 @@
-/** Default help text, `invalid` error, `disabled` hint and a hint with `Hint.Icon`. Use it to pick the right message style under a field. */
-import { Hint, Icon } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** Default help text next to an error and a hint under a disabled control — `invalid`, `disabled`. */
+import { Hint, Typography } from "prime-ui-kit";
 
 export default function HintStatesExample() {
   return (
-    <div className={styles.list}>
-      <Hint.Root>Формат: +7 900 000-00-00</Hint.Root>
-      <Hint.Root invalid>Введите 10 или 12 цифр ИНН.</Hint.Root>
-      <Hint.Root disabled>Лимит задаётся тарифом и не редактируется.</Hint.Root>
-      <Hint.Root>
-        <Hint.Icon>
-          <Icon name="field.email" />
-        </Hint.Icon>
-        На этот адрес придёт код подтверждения.
-      </Hint.Root>
+    <div>
+      <div>
+        <Hint.Root>Формат: +7 900 000-00-00</Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          default
+        </Typography>
+      </div>
+      <div>
+        <Hint.Root invalid>Введите 10 или 12 цифр ИНН.</Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          invalid
+        </Typography>
+      </div>
+      <div>
+        <Hint.Root disabled>Лимит задаётся тарифом.</Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled
+        </Typography>
+      </div>
     </div>
   );
 }

package/src/components/hint/examples/with-icon.tsx

@@ -0,0 +1,31 @@
+/** A leading icon centred on the first line, in the default and the error state — `Hint.Icon`. */
+import { Hint, Icon, Typography } from "prime-ui-kit";
+
+export default function HintWithIconExample() {
+  return (
+    <div>
+      <div>
+        <Hint.Root>
+          <Hint.Icon>
+            <Icon name="field.email" />
+          </Hint.Icon>
+          На этот адрес придёт код подтверждения.
+        </Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          default
+        </Typography>
+      </div>
+      <div>
+        <Hint.Root invalid>
+          <Hint.Icon>
+            <Icon name="status.danger" />
+          </Hint.Icon>
+          Адрес уже занят другим аккаунтом.
+        </Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          invalid
+        </Typography>
+      </div>
+    </div>
+  );
+}