prime-ui-kit 0.17.0 → 0.19.0

package/dist/skill/reference/components/field-list/examples/screen.tsx

@@ -1,4 +1,4 @@
-/** A record editor as a document page, a long form whose title, description and save stand in the content header: a plan's name, its specs and prices in one form; repeating records as FieldList rows with the headings once, a base price pinned above its changes, one value in three currencies in one row — `getLocked`, `compact`. */
+/** A record editor as a document page, a long form whose title, description and save stand in the content header and whose blocks are titled cards one under another: a plan's name, its specs and prices; repeating records as FieldList rows with the headings once, an icon and its color side by side, a base price pinned above its changes, one value in three currencies in one row — `getLocked`, `compact`. */
 import {
   Button,
   Card,
@@ -29,9 +29,9 @@ type Period = { id: string; from: string; price: string; base?: boolean };
 
 const SPEC_COLUMNS: FieldListColumn[] = [
   { label: "Иконка", width: "compact" },
+  { label: "Цвет", width: "compact" },
   { label: "Параметр" },
   { label: "Значение" },
-  { label: "Цвет", width: "compact" },
 ];
 
 const SPEC_ICONS: { name: IconName; label: string }[] = [
@@ -97,6 +97,7 @@ const SAVED_MS = 2000;
 
 export default function FieldListScreenExample() {
   const formId = React.useId();
+  const specsTitleId = React.useId();
   const [specs, setSpecs] = React.useState(SPECS);
   const [periods, setPeriods] = React.useState(PERIODS);
   const [nameError, setNameError] = React.useState<string>();
@@ -134,182 +135,187 @@ export default function FieldListScreenExample() {
         </Page.Actions>
       </Page.Header>
       <Page.Body>
-        <Page.Section layout="aside" label="Основное">
-          <form id={formId} noValidate onSubmit={save}>
-            <Card.Root variant="panel">
-              <Card.Body>
-                <Fieldset disabled={saving} aria-label="Основное">
-                  <Input.Root label="Название" error={nameError}>
+        <form id={formId} noValidate onSubmit={save}>
+          <Card.Root variant="panel">
+            <Card.Header>
+              <Card.Title as="h2">Основное</Card.Title>
+            </Card.Header>
+            <Card.Body>
+              <Fieldset disabled={saving} aria-label="Основное">
+                <Input.Root label="Название" error={nameError}>
+                  <Input.Wrapper>
+                    <Input.Field name="name" defaultValue="Команда" />
+                  </Input.Wrapper>
+                </Input.Root>
+                <Textarea.Root
+                  name="summary"
+                  label="Описание"
+                  optional
+                  rows={2}
+                  defaultValue="Для отделов до 50 человек: задачи, документы и отчёты в одном месте."
+                />
+              </Fieldset>
+            </Card.Body>
+          </Card.Root>
+        </form>
+        <Card.Root variant="panel">
+          <Card.Header>
+            <Card.Title as="h2" id={specsTitleId}>
+              Характеристики
+            </Card.Title>
+            <Card.Description>Первые три закреплены: их видно в карточке тарифа.</Card.Description>
+          </Card.Header>
+          <Card.Body>
+            <FieldList
+              aria-labelledby={specsTitleId}
+              disabled={saving}
+              columns={SPEC_COLUMNS}
+              reorderable
+              value={specs}
+              onValueChange={setSpecs}
+              getId={(spec) => spec.id}
+              getLabel={(spec) => spec.name}
+              getLocked={(spec) => spec.pinned ?? false}
+              createItem={(): Spec => ({
+                id: crypto.randomUUID(),
+                icon: "object.globe",
+                name: "",
+                value: "",
+                color: "#14b8a6",
+              })}
+              addLabel="Добавить характеристику"
+              renderItem={(spec, row) => (
+                <>
+                  <Select.Root
+                    value={spec.icon}
+                    onValueChange={(icon) => row.update({ icon: icon as IconName })}
+                  >
+                    <Select.Trigger>
+                      <Select.TriggerIcon>
+                        <Icon name={spec.icon} />
+                      </Select.TriggerIcon>
+                    </Select.Trigger>
+                    <Select.Content>
+                      {SPEC_ICONS.map((icon) => (
+                        <Select.Item key={icon.name} value={icon.name}>
+                          <Select.ItemIcon>
+                            <Icon name={icon.name} />
+                          </Select.ItemIcon>
+                          {icon.label}
+                        </Select.Item>
+                      ))}
+                    </Select.Content>
+                  </Select.Root>
+                  <ColorPresets.Root
+                    value={spec.color}
+                    onValueChange={(color) => row.update({ color: color ?? spec.color })}
+                  >
+                    <ColorPresets.Trigger>
+                      <ColorPresets.SwatchButton />
+                    </ColorPresets.Trigger>
+                    <ColorPresets.Content />
+                  </ColorPresets.Root>
+                  <Input.Root>
                     <Input.Wrapper>
-                      <Input.Field name="name" defaultValue="Команда" />
+                      <Input.Field
+                        value={spec.name}
+                        onChange={(event) => row.update({ name: event.target.value })}
+                      />
                     </Input.Wrapper>
                   </Input.Root>
-                  <Textarea.Root
-                    name="summary"
-                    label="Описание"
-                    optional
-                    rows={2}
-                    defaultValue="Для отделов до 50 человек: задачи, документы и отчёты в одном месте."
-                  />
-                </Fieldset>
-              </Card.Body>
-            </Card.Root>
-          </form>
-        </Page.Section>
-
-        <Page.Section layout="aside" label="Характеристики">
-          <Card.Root variant="panel">
-            <Card.Body>
+                  <Input.Root>
+                    <Input.Wrapper>
+                      <Input.Field
+                        value={spec.value}
+                        onChange={(event) => row.update({ value: event.target.value })}
+                      />
+                    </Input.Wrapper>
+                  </Input.Root>
+                </>
+              )}
+            />
+          </Card.Body>
+        </Card.Root>
+        <Card.Root variant="panel">
+          <Card.Header>
+            <Card.Title as="h2">Стоимость</Card.Title>
+          </Card.Header>
+          <Card.Body className={styles.groups}>
+            <Fieldset label="За месяц" disabled={saving}>
               <FieldList
-                aria-label="Характеристики"
-                disabled={saving}
-                columns={SPEC_COLUMNS}
-                reorderable
-                value={specs}
-                onValueChange={setSpecs}
-                getId={(spec) => spec.id}
-                getLabel={(spec) => spec.name}
-                getLocked={(spec) => spec.pinned ?? false}
-                createItem={(): Spec => ({
-                  id: crypto.randomUUID(),
-                  icon: "object.globe",
-                  name: "",
-                  value: "",
-                  color: "#14b8a6",
-                })}
-                addLabel="Добавить характеристику"
-                renderItem={(spec, row) => (
+                columns={PRICE_COLUMNS}
+                value={periods}
+                onValueChange={setPeriods}
+                getId={(period) => period.id}
+                getLocked={(period) => period.base ?? false}
+                labels={{ lockedReason: "Базовую цену нельзя удалить" }}
+                createItem={() => ({ id: crypto.randomUUID(), from: "", price: "" })}
+                addLabel="Добавить изменение цены"
+                renderItem={(period, row) => (
                   <>
-                    <Select.Root
-                      value={spec.icon}
-                      onValueChange={(icon) => row.update({ icon: icon as IconName })}
-                    >
-                      <Select.Trigger>
-                        <Select.TriggerIcon>
-                          <Icon name={spec.icon} />
-                        </Select.TriggerIcon>
-                      </Select.Trigger>
-                      <Select.Content>
-                        {SPEC_ICONS.map((icon) => (
-                          <Select.Item key={icon.name} value={icon.name}>
-                            <Select.ItemIcon>
-                              <Icon name={icon.name} />
-                            </Select.ItemIcon>
-                            {icon.label}
-                          </Select.Item>
-                        ))}
-                      </Select.Content>
-                    </Select.Root>
-                    <Input.Root>
-                      <Input.Wrapper>
-                        <Input.Field
-                          value={spec.name}
-                          onChange={(event) => row.update({ name: event.target.value })}
-                        />
-                      </Input.Wrapper>
-                    </Input.Root>
-                    <Input.Root>
-                      <Input.Wrapper>
-                        <Input.Field
-                          value={spec.value}
-                          onChange={(event) => row.update({ value: event.target.value })}
-                        />
-                      </Input.Wrapper>
-                    </Input.Root>
-                    <ColorPresets.Root
-                      value={spec.color}
-                      onValueChange={(color) => row.update({ color: color ?? spec.color })}
-                    >
-                      <ColorPresets.Trigger>
-                        <ColorPresets.SwatchButton />
-                      </ColorPresets.Trigger>
-                      <ColorPresets.Content />
-                    </ColorPresets.Root>
-                  </>
-                )}
-              />
-            </Card.Body>
-          </Card.Root>
-        </Page.Section>
-
-        <Page.Section layout="aside" label="Стоимость">
-          <Card.Root variant="panel">
-            <Card.Body className={styles.groups}>
-              <Fieldset label="За месяц" disabled={saving}>
-                <FieldList
-                  columns={PRICE_COLUMNS}
-                  value={periods}
-                  onValueChange={setPeriods}
-                  getId={(period) => period.id}
-                  getLocked={(period) => period.base ?? false}
-                  createItem={() => ({ id: crypto.randomUUID(), from: "", price: "" })}
-                  addLabel="Добавить изменение цены"
-                  renderItem={(period, row) => (
-                    <>
-                      {period.base ? (
-                        <Input.Root>
-                          <Input.Wrapper>
-                            <Input.Field value="Всегда, если нет изменений" readOnly />
-                          </Input.Wrapper>
-                        </Input.Root>
-                      ) : (
-                        <Select.Root
-                          value={period.from}
-                          onValueChange={(from) => row.update({ from })}
-                          placeholder="Выберите месяц"
-                        >
-                          <Select.Trigger>
-                            <Select.Value />
-                          </Select.Trigger>
-                          <Select.Content>
-                            {MONTHS.map((month) => (
-                              <Select.Item key={month.value} value={month.value}>
-                                {month.label}
-                              </Select.Item>
-                            ))}
-                          </Select.Content>
-                        </Select.Root>
-                      )}
+                    {period.base ? (
                       <Input.Root>
                         <Input.Wrapper>
-                          <Input.Field
-                            value={period.price}
-                            inputMode="decimal"
-                            placeholder="0"
-                            onChange={(event) => row.update({ price: event.target.value })}
-                          />
-                          <Input.InlineAffix side="end">₽</Input.InlineAffix>
+                          <Input.Field value="Всегда, если нет изменений" readOnly />
                         </Input.Wrapper>
                       </Input.Root>
-                    </>
-                  )}
-                />
-              </Fieldset>
-              <Fieldset
-                label="Подключение"
-                description="Разовый платёж; пустая валюта не выставляется."
-                disabled={saving}
-              >
-                <div className={styles.currencies}>
-                  {SETUP_FEE.map((fee) => (
-                    <Input.Root key={fee.name}>
+                    ) : (
+                      <Select.Root
+                        value={period.from}
+                        onValueChange={(from) => row.update({ from })}
+                        placeholder="Выберите месяц"
+                      >
+                        <Select.Trigger>
+                          <Select.Value />
+                        </Select.Trigger>
+                        <Select.Content>
+                          {MONTHS.map((month) => (
+                            <Select.Item key={month.value} value={month.value}>
+                              {month.label}
+                            </Select.Item>
+                          ))}
+                        </Select.Content>
+                      </Select.Root>
+                    )}
+                    <Input.Root>
                       <Input.Wrapper>
                         <Input.Field
-                          name={fee.name}
-                          aria-label={fee.label}
+                          value={period.price}
                           inputMode="decimal"
                           placeholder="0"
-                          defaultValue={fee.value}
+                          onChange={(event) => row.update({ price: event.target.value })}
                         />
-                        <Input.InlineAffix side="end">{fee.currency}</Input.InlineAffix>
+                        <Input.InlineAffix side="end">₽</Input.InlineAffix>
                       </Input.Wrapper>
                     </Input.Root>
-                  ))}
-                </div>
-              </Fieldset>
-            </Card.Body>
-          </Card.Root>
-        </Page.Section>
+                  </>
+                )}
+              />
+            </Fieldset>
+            <Fieldset
+              label="Подключение"
+              description="Разовый платёж; пустая валюта не выставляется."
+              disabled={saving}
+            >
+              <div className={styles.currencies}>
+                {SETUP_FEE.map((fee) => (
+                  <Input.Root key={fee.name}>
+                    <Input.Wrapper>
+                      <Input.Field
+                        name={fee.name}
+                        aria-label={fee.label}
+                        inputMode="decimal"
+                        placeholder="0"
+                        defaultValue={fee.value}
+                      />
+                      <Input.InlineAffix side="end">{fee.currency}</Input.InlineAffix>
+                    </Input.Wrapper>
+                  </Input.Root>
+                ))}
+              </div>
+            </Fieldset>
+          </Card.Body>
+        </Card.Root>
       </Page.Body>
     </Page.Root>
   );

package/dist/skill/reference/components/field-list/examples/totals.tsx

@@ -0,0 +1,83 @@
+/** A deal bonus split between the team: the share takes a narrow column, and the totals row under the lines sums the shares and the amounts, each ending where its fields end their numbers — `renderTotals`, `width`. */
+import { FieldList, type FieldListColumn, Input } from "prime-ui-kit";
+import * as React from "react";
+
+type Share = { id: string; member: string; percent: string };
+
+const BONUS = 240_000;
+
+const COLUMNS: FieldListColumn[] = [
+  { label: "Участник" },
+  { label: "Доля", width: "xs" },
+  { label: "Сумма", width: "m" },
+];
+
+const SHARES: Share[] = [
+  { id: "sokolova", member: "Анна Соколова", percent: "50" },
+  { id: "demin", member: "Олег Демин", percent: "30" },
+  { id: "kotova", member: "Ирина Котова", percent: "20" },
+];
+
+const AMOUNT = new Intl.NumberFormat("ru-RU", { maximumFractionDigits: 0 });
+
+const percentOf = (share: Share) => Number(share.percent.replace(",", ".")) || 0;
+
+export default function FieldListTotalsExample() {
+  const [shares, setShares] = React.useState(SHARES);
+
+  return (
+    <FieldList
+      label="Бонус по сделке"
+      hint="Доли в сумме дают 100 %."
+      columns={COLUMNS}
+      value={shares}
+      onValueChange={setShares}
+      getId={(share) => share.id}
+      getLabel={(share) => share.member}
+      createItem={() => ({ id: crypto.randomUUID(), member: "", percent: "" })}
+      addLabel="Добавить участника"
+      renderItem={(share, row) => (
+        <>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Field
+                value={share.member}
+                onChange={(event) => row.update({ member: event.target.value })}
+              />
+            </Input.Wrapper>
+          </Input.Root>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Field
+                value={share.percent}
+                inputMode="decimal"
+                onChange={(event) => row.update({ percent: event.target.value })}
+              />
+              <Input.InlineAffix side="end">%</Input.InlineAffix>
+            </Input.Wrapper>
+          </Input.Root>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Field
+                value={AMOUNT.format((BONUS * percentOf(share)) / 100)}
+                inputMode="decimal"
+                readOnly
+              />
+              <Input.InlineAffix side="end">₽</Input.InlineAffix>
+            </Input.Wrapper>
+          </Input.Root>
+        </>
+      )}
+      renderTotals={(items) => {
+        const percent = items.reduce((sum, share) => sum + percentOf(share), 0);
+        return (
+          <>
+            {null}
+            {`${percent} %`}
+            {`${AMOUNT.format((BONUS * percent) / 100)} ₽`}
+          </>
+        );
+      }}
+    />
+  );
+}

package/dist/skill/reference/components/file-upload/COMPONENT.md

@@ -120,6 +120,7 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | `required` | `boolean` | — | Red `*` after the label and native `required` on the input. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the field. Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message under the field (a rejected file, too few files); implies `invalid`. |
 | `invalid` | `boolean` | — | Danger line and icon of the zone, `aria-invalid` on the input. A non-empty `error` implies it. |
 | `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring of the drop zone and the add tile (`data-focus-ring="false"`); focus, keyboard and ARIA stay. The picker Button keeps its ring. |

package/dist/skill/reference/components/hint/COMPONENT.md

@@ -8,6 +8,7 @@
 ## When to use
 - Under a control without `hint` / `error` props (an embedded `Datepicker.Panel`, 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.
+- A status the field's value has (a deadline that nears, a check that passed): `tone`, with the status in the words.
 
 ## When not to use
 - Input, Textarea, Select, Checkbox, Slider, SegmentedControl 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), [Slider](../slider/COMPONENT.md)).
@@ -36,6 +37,7 @@ Hint.Root      <p> with the text
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the paired field: 12/16 for xs–m, 13/20 for l and xl. Without it the tier of its host, else `m`. |
+| `tone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of the text (a deadline that nears, a check that passed). The words carry the status, the color repeats it; `invalid` and `disabled` take over the color. |
 | `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. A disabled `Fieldset` around the hint sets it too. |
 | `children` | `ReactNode` | — | Text, optionally with `Hint.Icon` first. |
@@ -49,7 +51,15 @@ Hint.Root      <p> with the text
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the glyph), `className` and the other span attributes. |
 
 ## Variants
-Hint has no `variant` or `tone`; its states are flags.
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | Muted text | Format rules, limits, where the value comes from | yes |
+| `success` | Success text | The value passed a check («ИНН проверен») | |
+| `warning` | Warning text | The value needs attention soon («Осталось 12 дней») | |
+| `danger` | Danger text, no `aria-invalid` | A status of the data, not a validation error («Срок истёк») | |
+
+The words carry the status; the color only repeats it, and a `Hint.Icon` with the status glyph adds a shape. A validation error is `invalid` (or a field's `error`), never `tone="danger"`. `invalid` and `disabled` take over the tone's color.
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -68,11 +78,12 @@ The hint is always smaller than the field text; use the field's size.
 | `invalid` | Danger text, drops in | Validation error | `false` |
 | `disabled` | Disabled text | Under a disabled control | `false` |
 
-**Combinations** — one element switches between the hint text and the error text with `invalid` (no layout jump); a standalone hint that changes after an action stays mounted with `aria-live="polite"` (inside a field the frame does it). `invalid` and `disabled` together make no sense. 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); a standalone hint that changes after an action stays mounted with `aria-live="polite"` (inside a field the frame does it). `invalid` and `disabled` together make no sense. A result of the whole form goes to a [Banner](../banner/COMPONENT.md), not a toned hint.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
+| status | `tone` | `data-tone` with the shared text tone (none for `neutral`, and none while `invalid` or `disabled`); the color eases between tones |
 | 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`, or a disabled `Fieldset` around it | `data-disabled="true"` |
 | size | `size`, else the host tier | `data-size` |
@@ -106,6 +117,7 @@ No `labels`.
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Help text under a calendar that has no hint of its own, linked to it through `id` and `aria-describedby` — `id`. |
+| [variants.tsx](examples/variants.tsx) | Status hints whose words carry the status and the color repeats it — `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier, one per field tier: 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`. |
@@ -116,6 +128,8 @@ No `labels`.
 - A separate hint and error element at the same time → one element; the error replaces the hint.
 - Hint without `id` + `aria-describedby` → the screen reader does not connect it to the field.
 - Hint size different from the field size → use the same `size`, or none inside a sized host.
+- `tone="danger"` for a validation error → `invalid` (or the field's `error`): only it sets `aria-invalid`.
+- A status by color alone («12 д.» in orange) → the words say it («Осталось 12 дней»), the tone repeats it.
 - `role="alert"` on a field error → none; the field frame announces it, a standalone hint takes `aria-live="polite"`.
 
 ## Related

package/dist/skill/reference/components/hint/examples/variants.tsx

@@ -0,0 +1,48 @@
+/** Status hints whose words carry the status and the color repeats it — `tone`. */
+import { Hint, Icon, Typography } from "prime-ui-kit";
+
+export default function HintVariantsExample() {
+  return (
+    <div>
+      <div>
+        <Hint.Root>Действует до 30 ноября.</Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          neutral
+        </Typography>
+      </div>
+      <div>
+        <Hint.Root tone="success">
+          <Hint.Icon>
+            <Icon name="status.success" />
+          </Hint.Icon>
+          ИНН проверен в ФНС.
+        </Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          success
+        </Typography>
+      </div>
+      <div>
+        <Hint.Root tone="warning">
+          <Hint.Icon>
+            <Icon name="status.warning" />
+          </Hint.Icon>
+          Осталось 12 дней.
+        </Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          warning
+        </Typography>
+      </div>
+      <div>
+        <Hint.Root tone="danger">
+          <Hint.Icon>
+            <Icon name="status.danger" />
+          </Hint.Icon>
+          Срок истёк 3 дня назад.
+        </Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          danger
+        </Typography>
+      </div>
+    </div>
+  );
+}