@eocrm/design-system 0.6.22 → 0.6.23

package/docs/i18n.md

@@ -0,0 +1,74 @@
+# Localization (i18n)
+
+How library strings are translated, and how to pair `I18nProvider` with `LocaleProvider`.
+
+Every user-facing string the library renders — visible text, aria-labels, placeholders, default empty/loading copy — flows through a single React Context. Wrap your app once; every component picks up the right copy. There are NO `labels` / `cancelLabel` / `searchPlaceholder` props on any component.
+
+```tsx
+import { I18nProvider } from '@eocrm/design-system';
+
+<I18nProvider locale="ru">
+  <App />
+</I18nProvider>;
+```
+
+**Overrides** are a deep-partial of the messages tree:
+
+```tsx
+<I18nProvider
+  locale="ru"
+  overrides={{
+    pagination: { next: 'Дальше' },
+    badge: { modified: 'Изменено!' },
+  }}
+>
+  <App />
+</I18nProvider>
+```
+
+- Missing override keys fall back to the locale defaults.
+- Missing locale keys do NOT fall back to `en` — `I18nProvider` uses the one locale catalogue and `useTranslation` warns and returns the literal key string. The real guard is the type: `en` and `ru` are both annotated `: Messages` (total, not partial), so a missing key is a `tsc` error and cannot ship.
+- No provider at all = `en` defaults.
+
+**Available locales:** `'en'` (default), `'ru'`. v1.
+
+**`I18nProvider` vs `LocaleProvider` — pair them.** `I18nProvider` carries the message catalog (translated strings). `LocaleProvider` carries the BCP-47 tag used by `Intl.*` formatters inside Calendar / DatePicker / DateRangePicker (month names, weekday order, date-range formatting). They are independent — a Russian app should wrap with BOTH so visible strings AND Intl-rendered dates speak the right language:
+
+```tsx
+<I18nProvider locale="ru">
+  <LocaleProvider locale="ru-RU">
+    <App />
+  </LocaleProvider>
+</I18nProvider>
+```
+
+**Adding a new string in a library component**:
+
+1. Add the key to `src/i18n/messages.ts` (`Messages` interface).
+2. Add the English value to `src/i18n/en.ts`.
+3. Add the Russian value to `src/i18n/ru.ts` (use `ruPlural()` from `i18n/format.ts` for count-varying strings).
+4. In the component, `const t = useTranslation();` then `aria-label={t('component.key')}`. For array messages (months / weekdays), use `useTranslationArray()`.
+5. Never inline an English string — `aria-label="Close"` is a Hard rule 9 violation.
+
+**Drag-and-drop announcements** are localized too. Every drag surface (`Sortable`,
+`SortableGroup`, `Kanban`, `DataTable` column reorder, `RichTextEditor` block
+gutter) overrides dnd-kit's English defaults with the `drag.*` messages, and
+names what it drags by its **rendered text** rather than its id — "Amount due,
+position 3 of 7", not "col_amount was moved over droppable area col_name". Text
+is read from the DOM, so a closed `DropdownMenu` / `Tooltip` / `Popover` inside
+a card contributes nothing, and `aria-hidden` decoration is skipped.
+
+Two things are worth doing yourself:
+
+```tsx
+{/* Name the CONTAINER — the library can't invent one. Either attribute works. */}
+<Kanban.Column id="qualified" aria-label="Qualified">          {/* → "…in Qualified" */}
+<Kanban.Column id="qualified" aria-labelledby="qualified-h">   {/* same, from the heading */}
+<SortableGroup.Container id="review" items={ids} aria-label="In review" />
+
+{/* Override a chatty ITEM. Without this the whole card is read out. */}
+<Kanban.Card id="d-1" aria-label="Acme renewal">…title, owner, due date, badges…</Kanban.Card>
+<Sortable.Item id="f-1" aria-label="Company name">…</Sortable.Item>
+```
+
+An unnamed container falls back to its position ("column 2 of 3").

package/docs/typescript.md

@@ -0,0 +1,9 @@
+# TypeScript
+
+Getting prop types to resolve in your editor.
+
+Every prop and variant type is typed. If your editor shows no types:
+
+- Confirm `moduleResolution: "bundler"` (or `"node16"`) in your `tsconfig.json`.
+- Confirm your IDE's TS server is running.
+- The package's `types` field points at `./src/index.ts` — source distribution means the consumer's bundler compiles `.tsx`. Vite, Next.js, Webpack 5+ all support this; older configurations may need `transpilePackages: ['@eocrm/design-system']` (Next.js) or equivalent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eocrm/design-system",
-  "version": "0.6.22",
+  "version": "0.6.23",
   "description": "Design system for the EOCRM product — React 19 + SCSS modules + CSS custom properties.",
   "license": "Apache-2.0",
   "type": "module",
@@ -50,7 +50,7 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@eocrm/design-tokens": "0.6.22",
+    "@eocrm/design-tokens": "0.6.23",
     "@floating-ui/react-dom": "^2.1.8",
     "@types/d3-scale": "^4.0.9",
     "@types/d3-shape": "^3.2.0",

package/src/components/LiquidEditor/useLiquidAutocomplete.ts

@@ -127,7 +127,7 @@ export function useLiquidAutocomplete({ variables, filters, enabled }: UseLiquid
         // `||`, not `??`. This is the SAME prop as InsertVariableMenu's, and it
         // feeds `AutocompleteMenu`'s `<span>{item.label}</span>` — a
         // `role="option"`'s only name source. `label: ''` rendered a blank
-        // option, and the docs in `types.ts` and AI-PRIMER.md promise it cannot.
+        // option, and the docs in `types.ts` and docs/accessible-names.md promise it cannot.
         label: v.label || v.code,
         type: v.type,
         group: v.group,

package/src/components/RichText/RichTextAttachment.tsx

@@ -94,7 +94,7 @@ export function RichTextAttachment({ block, editable }: { block: Block; editable
         // `alt=""` is a real HTML value — "decorative, skip me" — so an empty
         // `block.alt` is a choice to honour, not an unset to fall back from.
         // Everywhere else in this library an empty label means unset; see
-        // AI-PRIMER.md, which names this as the exception.
+        // docs/accessible-names.md, which names this as the exception.
         alt={block.alt ?? name}
         width={block.width}
         height={block.height}

package/src/i18n/I18nProvider.tsx

@@ -32,7 +32,7 @@ export interface I18nProviderProps {
 
 /**
  * Provides the message catalog (`locale` plus optional `overrides`) to descendants.
- * @see AI-PRIMER.md#localization-i18n
+ * @see docs/i18n.md
  */
 export function I18nProvider({ locale, overrides, children }: I18nProviderProps) {
   const value = useMemo<I18nContextValue>(() => {