@startsimpli/ui 0.4.90 → 0.4.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.90",
+  "version": "0.4.92",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -12,6 +12,7 @@
     "./gantt/styles": "./src/components/gantt/gantt.css",
     "./components": "./src/components/index.ts",
     "./error": "./src/components/error/index.ts",
+    "./i18n": "./src/components/i18n/index.ts",
     "./utils": "./src/utils/index.ts",
     "./theme": "./src/theme/index.ts",
     "./theme/contract": "./theme/contract.css",
@@ -44,6 +45,7 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "@startsimpli/auth": "^0.4.34",
+    "@startsimpli/i18n": "^0.1.1",
     "@startsimpli/api": "^0.5.54"
   },
   "peerDependenciesMeta": {
@@ -53,6 +55,9 @@
     "@startsimpli/auth": {
       "optional": true
     },
+    "@startsimpli/i18n": {
+      "optional": true
+    },
     "@startsimpli/realtime": {
       "optional": true
     },
@@ -115,6 +120,7 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
+    "@startsimpli/i18n": "0.1.1",
     "@startsimpli/realtime": "0.0.2"
   },
   "keywords": [

package/src/components/__tests__/locale-switcher.test.tsx

@@ -0,0 +1,78 @@
+/**
+ * startsim-768w.35.1 — the language control itself.
+ *
+ * The switcher is the one screen element that must make sense to someone who
+ * cannot read the current language. That constrains it more than a normal
+ * control: every option is written in its OWN language, each carries its own
+ * `lang`/`dir` so العربية isn't rendered by LTR rules, and the trigger is an
+ * icon rather than a word in whichever language the user is trying to leave.
+ */
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+import { LocaleSwitcher, type LocaleOption } from '../i18n/LocaleSwitcher'
+
+const locales: LocaleOption[] = [
+  { code: 'en', name: 'English', nativeName: 'English', dir: 'ltr' },
+  { code: 'ar', name: 'Arabic', nativeName: 'العربية', dir: 'rtl' },
+]
+
+describe('LocaleSwitcher — inline', () => {
+  it('offers every language by its own name and reports the active one', () => {
+    render(<LocaleSwitcher variant="inline" locales={locales} value="en" onChange={() => {}} />)
+
+    const english = screen.getByRole('radio', { name: 'English' })
+    const arabic = screen.getByRole('radio', { name: 'العربية' })
+
+    expect(english).toHaveAttribute('aria-checked', 'true')
+    expect(arabic).toHaveAttribute('aria-checked', 'false')
+  })
+
+  it('labels each option with its own language and direction', () => {
+    render(<LocaleSwitcher variant="inline" locales={locales} value="en" onChange={() => {}} />)
+
+    const arabic = screen.getByRole('radio', { name: 'العربية' })
+    expect(arabic).toHaveAttribute('lang', 'ar')
+    expect(arabic).toHaveAttribute('dir', 'rtl')
+  })
+
+  it('hands the chosen code to the caller', async () => {
+    const onChange = jest.fn()
+    render(<LocaleSwitcher variant="inline" locales={locales} value="en" onChange={onChange} />)
+
+    await userEvent.click(screen.getByRole('radio', { name: 'العربية' }))
+    expect(onChange).toHaveBeenCalledWith('ar')
+  })
+})
+
+describe('LocaleSwitcher — menu', () => {
+  it('names the trigger for screen readers and shows the active language on it', () => {
+    render(<LocaleSwitcher locales={locales} value="ar" onChange={() => {}} label="تغيير اللغة" />)
+
+    const trigger = screen.getByRole('button', { name: 'تغيير اللغة' })
+    expect(trigger).toHaveTextContent('العربية')
+  })
+
+  it('lists the languages as radios and switches on select', async () => {
+    const onChange = jest.fn()
+    render(<LocaleSwitcher locales={locales} value="en" onChange={onChange} />)
+
+    await userEvent.click(screen.getByRole('button', { name: 'Change language' }))
+
+    const options = await screen.findAllByRole('menuitemradio')
+    expect(options.map((o) => o.textContent)).toEqual(['English', 'العربية'])
+    expect(options[0]).toHaveAttribute('aria-checked', 'true')
+
+    await userEvent.click(screen.getByRole('menuitemradio', { name: 'العربية' }))
+    expect(onChange).toHaveBeenCalledWith('ar')
+  })
+})
+
+describe('LocaleSwitcher — nothing to switch', () => {
+  it('renders nothing when the app ships a single language', () => {
+    const { container } = render(
+      <LocaleSwitcher locales={[locales[0]]} value="en" onChange={() => {}} />
+    )
+    expect(container).toBeEmptyDOMElement()
+  })
+})

package/src/components/dashboard/DonutChart.tsx

@@ -22,6 +22,15 @@ export interface DonutChartProps {
   showLegend?: boolean
   /** Formats the right-hand column of a legend row. Defaults to the raw value. */
   formatLegendValue?: (segment: DonutSegment) => React.ReactNode
+  /**
+   * Narrowest a legend column may get, in px. The legend flows into as many
+   * columns as fit, so on a wide card it packs rows side by side instead of
+   * stretching each one — a legend row is a label and a number that belong
+   * together, and a 1400px row separates them by a metre of empty card.
+   */
+  legendColumnWidth?: number
+  /** Extra classes for the legend list — e.g. a `max-w-*` cap. */
+  legendClassName?: string
   /** Overrides the generated description. */
   ariaLabel?: string
   className?: string
@@ -81,6 +90,8 @@ export function DonutChart({
   thickness = 18,
   showLegend = false,
   formatLegendValue,
+  legendColumnWidth = 176,
+  legendClassName,
   ariaLabel,
   className,
 }: DonutChartProps) {
@@ -161,7 +172,22 @@ export function DonutChart({
       </div>
 
       {showLegend && segments.length > 0 && (
-        <ul className="min-w-0 flex-1 space-y-2">
+        // Columns, not one tall list. A legend row pairs a label with its
+        // number, so the row has to stay narrow enough for the eye to carry one
+        // to the other; `auto-fill` spends extra card width on more columns
+        // instead of on the gap inside every row.
+        <ul
+          className={cn(
+            'grid min-w-0 flex-1 gap-x-8 gap-y-2',
+            legendClassName,
+          )}
+          style={{
+            gridTemplateColumns: `repeat(auto-fill, minmax(${Math.max(
+              legendColumnWidth,
+              1,
+            )}px, 1fr))`,
+          }}
+        >
           {segments.map((segment, i) => (
             <li
               key={`${segment.label}-${i}`}

package/src/components/dashboard/__tests__/display-primitives.test.tsx

@@ -441,6 +441,35 @@ describe('DonutChart', () => {
     expect(screen.getByText('$6,800')).toBeInTheDocument()
   })
 
+  it('flows the legend into columns rather than one full-width row per segment', () => {
+    // A legend row is a label and its number, and the eye has to carry one to
+    // the other. Stretched across a wide card the pair ends up a metre apart
+    // with nothing in between, so the list is a grid that spends spare width on
+    // more columns instead of on the gap inside each row.
+    const { container } = render(<DonutChart segments={segments} showLegend />)
+    const list = container.querySelector('ul')!
+    expect(list.className).toContain('grid')
+    expect(list.style.gridTemplateColumns).toBe(
+      'repeat(auto-fill, minmax(176px, 1fr))',
+    )
+  })
+
+  it('lets the caller set the column width and add classes to the legend', () => {
+    const { container } = render(
+      <DonutChart
+        segments={segments}
+        showLegend
+        legendColumnWidth={240}
+        legendClassName="max-w-md"
+      />,
+    )
+    const list = container.querySelector('ul')!
+    expect(list.style.gridTemplateColumns).toBe(
+      'repeat(auto-fill, minmax(240px, 1fr))',
+    )
+    expect(list.className).toContain('max-w-md')
+  })
+
   it('uses caller colours for the arcs and falls back to currentColor', () => {
     const { container } = render(
       <DonutChart segments={[{ label: 'a', value: 1, color: '#FF0000' }, { label: 'b', value: 1 }]} />,

package/src/components/i18n/LocaleMenu.tsx

@@ -0,0 +1,26 @@
+'use client';
+
+import * as React from 'react';
+import { useLocale } from '@startsimpli/i18n';
+
+import { LocaleSwitcher, type LocaleSwitcherProps } from './LocaleSwitcher';
+
+export type LocaleMenuProps = Omit<LocaleSwitcherProps, 'locales' | 'value' | 'onChange'>;
+
+/**
+ * The switcher, already wired.
+ *
+ * Drop `<LocaleMenu />` anywhere inside an `<I18nProvider>` and language
+ * switching works — the provider owns the locale, persists the choice, and
+ * flips `<html dir>`. Apps should not be re-writing that three-line binding
+ * each time; `LocaleSwitcher` stays available for the rare header that needs
+ * to drive the control from somewhere else.
+ *
+ * Lives behind the `@startsimpli/ui/i18n` subpath because it imports
+ * `@startsimpli/i18n`, which is an OPTIONAL peer — apps that never touch this
+ * subpath never need the dependency.
+ */
+export function LocaleMenu(props: LocaleMenuProps) {
+  const { locale, setLocale, locales } = useLocale();
+  return <LocaleSwitcher {...props} locales={locales} value={locale} onChange={setLocale} />;
+}

package/src/components/i18n/LocaleSwitcher.tsx

@@ -0,0 +1,159 @@
+'use client';
+
+import * as React from 'react';
+import { Check, Languages } from 'lucide-react';
+
+import { cn } from '../../lib/utils';
+import { Button } from '../ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '../ui/dropdown-menu';
+
+/**
+ * One selectable language. Structurally compatible with `LocaleConfig` from
+ * `@startsimpli/i18n`, but declared locally on purpose: this component stays a
+ * plain presentational control that any app can drive, i18n package or not.
+ */
+export interface LocaleOption {
+  code: string;
+  name: string;
+  /** The language's name in its own language — what actually goes on screen. */
+  nativeName?: string;
+  dir?: 'ltr' | 'rtl';
+}
+
+export interface LocaleSwitcherProps {
+  locales: readonly LocaleOption[];
+  /** Active locale code. */
+  value: string;
+  onChange: (code: string) => void;
+  /** `menu` = icon + dropdown (any number of languages). `inline` = segmented
+   *  buttons, all languages visible at once — good for exactly two. */
+  variant?: 'menu' | 'inline';
+  /** Show the active language's name beside the icon (`menu` only). */
+  showLabel?: boolean;
+  align?: 'start' | 'center' | 'end';
+  /** Accessible name for the control. Callers pass a translated string; the
+   *  English default is only a floor, not a design choice. */
+  label?: string;
+  className?: string;
+}
+
+/** What to show for a language: its own name, falling back to the English one. */
+function displayName(locale: LocaleOption): string {
+  return locale.nativeName || locale.name;
+}
+
+/**
+ * Language picker.
+ *
+ * Presentational and controlled — it holds no locale state and imports no i18n
+ * runtime. Wire it to whatever owns the locale (`<LocaleMenu />` in this package
+ * does exactly that against `@startsimpli/i18n`).
+ *
+ * Two details that are easy to get wrong and matter here:
+ *
+ * - Every option carries its OWN `dir`. A menu rendered LTR that prints العربية
+ *   without `dir="rtl"` on that item mis-orders any punctuation or digits beside
+ *   it. Each language label is a little island of its own direction.
+ * - The trigger is labelled with the icon, never with a flag. Flags are
+ *   countries, not languages — Arabic isn't one flag, and picking one is a
+ *   political statement nobody asked the switcher to make.
+ */
+export function LocaleSwitcher({
+  locales,
+  value,
+  onChange,
+  variant = 'menu',
+  showLabel = true,
+  align = 'end',
+  label = 'Change language',
+  className,
+}: LocaleSwitcherProps) {
+  // A picker with one option is a label pretending to be a control.
+  if (locales.length < 2) return null;
+
+  const active = locales.find((l) => l.code === value);
+
+  if (variant === 'inline') {
+    return (
+      <div
+        role="radiogroup"
+        aria-label={label}
+        dir="ltr"
+        className={cn(
+          'inline-flex items-center gap-0.5 rounded-md border border-border bg-muted/40 p-0.5',
+          className
+        )}
+      >
+        {locales.map((locale) => {
+          const selected = locale.code === value;
+          return (
+            <button
+              key={locale.code}
+              type="button"
+              role="radio"
+              aria-checked={selected}
+              lang={locale.code}
+              dir={locale.dir ?? 'ltr'}
+              onClick={() => onChange(locale.code)}
+              className={cn(
+                'rounded px-2.5 py-1 text-xs font-medium transition-colors',
+                'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+                selected
+                  ? 'bg-background text-foreground shadow-sm'
+                  : 'text-muted-foreground hover:text-foreground'
+              )}
+            >
+              {displayName(locale)}
+            </button>
+          );
+        })}
+      </div>
+    );
+  }
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button
+          variant="ghost"
+          size="sm"
+          aria-label={label}
+          className={cn('gap-2 text-muted-foreground hover:text-foreground', className)}
+        >
+          <Languages className="h-4 w-4 shrink-0" aria-hidden="true" />
+          {showLabel && active ? (
+            <span lang={active.code} dir={active.dir ?? 'ltr'} className="text-xs font-medium">
+              {displayName(active)}
+            </span>
+          ) : null}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align={align} className="min-w-[10rem]">
+        {/* Radio semantics on a plain Item rather than DropdownMenuRadioItem:
+            that primitive reserves its indicator gutter with physical `pl-8`,
+            which lands on the wrong side once the document flips to RTL. */}
+        {locales.map((locale) => (
+          <DropdownMenuItem
+            key={locale.code}
+            role="menuitemradio"
+            aria-checked={locale.code === value}
+            lang={locale.code}
+            dir={locale.dir ?? 'ltr'}
+            onSelect={() => onChange(locale.code)}
+            className="gap-6"
+          >
+            <span>{displayName(locale)}</span>
+            {locale.code === value ? (
+              <Check className="ms-auto h-4 w-4 shrink-0 opacity-70" aria-hidden="true" />
+            ) : null}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/components/i18n/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Language selection UI.
+ *
+ * - `LocaleSwitcher` — presentational + controlled, no i18n runtime.
+ * - `LocaleMenu` — the same control bound to `@startsimpli/i18n` (optional peer).
+ */
+export { LocaleSwitcher, type LocaleSwitcherProps, type LocaleOption } from './LocaleSwitcher';
+export { LocaleMenu, type LocaleMenuProps } from './LocaleMenu';