@cosmicdrift/kumiko-renderer 0.222.0 → 0.224.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.222.0",
+  "version": "0.224.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.222.0",
-    "@cosmicdrift/kumiko-headless": "0.222.0",
+    "@cosmicdrift/kumiko-framework": "0.224.0",
+    "@cosmicdrift/kumiko-headless": "0.224.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -25,7 +25,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "jsdom": "^29.1.1",
-    "@cosmicdrift/kumiko-locale-de": "0.222.0"
+    "@cosmicdrift/kumiko-locale-de": "0.224.0"
   },
   "repository": {
     "type": "git",

package/src/components/__tests__/multi-select-checkboxes.test.tsx

@@ -0,0 +1,162 @@
+// display: "checkboxes" on a multiSelect field renders a checkbox grid
+// (MultiSelectCheckboxes) instead of the combobox dropdown. Style follows
+// render-field-app-locale.test.tsx: mount RenderField under real Locale +
+// Primitives providers with capturing stubs, then invoke the captured
+// callbacks the way a real primitive implementation would.
+
+import { describe, expect, test } from "bun:test";
+import type { EditFieldViewModel } from "@cosmicdrift/kumiko-headless";
+import { render } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type ButtonProps,
+  type CorePrimitives,
+  type GridProps,
+  type InputProps,
+  PrimitivesProvider,
+} from "../../primitives";
+import { RenderField } from "../render-field";
+
+let capturedInputs: InputProps[] = [];
+let capturedButton: ButtonProps | undefined;
+let capturedGrid: GridProps | undefined;
+
+const captureInput: ComponentType<InputProps> = (props) => {
+  capturedInputs.push(props);
+  return null;
+};
+const captureButton: ComponentType<ButtonProps> = (props) => {
+  capturedButton = props;
+  return null;
+};
+const captureGrid: ComponentType<GridProps> = (props) => {
+  capturedGrid = props;
+  return <>{props.children}</>;
+};
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+const noop = (): ReactNode => null;
+
+const testPrimitives: CorePrimitives = {
+  Button: captureButton,
+  Banner: noop,
+  Field: passChildren,
+  Input: captureInput,
+  DataTable: noop,
+  Form: noop,
+  Section: noop,
+  Card: noop,
+  Grid: captureGrid,
+  GridCell: passChildren,
+  Text: noop,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+function languagesField(overrides: Partial<EditFieldViewModel> = {}): EditFieldViewModel {
+  return {
+    field: "languages",
+    label: "Languages",
+    type: "multiSelect",
+    value: [],
+    visible: true,
+    readOnly: false,
+    required: false,
+    options: ["en", "de", "es"],
+    optionLabels: { en: "English", de: "German", es: "Spanish" },
+    display: "checkboxes",
+    ...overrides,
+  };
+}
+
+let lastOnChange: unknown;
+function renderField(field: EditFieldViewModel): void {
+  capturedInputs = [];
+  capturedButton = undefined;
+  capturedGrid = undefined;
+  lastOnChange = undefined;
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver()}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <PrimitivesProvider value={testPrimitives}>
+        <RenderField field={field} onChange={(v) => (lastOnChange = v)} />
+      </PrimitivesProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("RenderField — multiSelect display: checkboxes", () => {
+  test("renders one boolean checkbox per option, no combobox", () => {
+    renderField(languagesField());
+    expect(capturedInputs).toHaveLength(3);
+    for (const input of capturedInputs) {
+      expect(input.kind).toBe("boolean");
+    }
+  });
+
+  test("without display, the field still renders the combobox (back-compat)", () => {
+    renderField(languagesField({ display: undefined }));
+    expect(capturedInputs).toHaveLength(1);
+    expect(capturedInputs[0]?.kind).toBe("combobox");
+  });
+
+  test("clicking one checkbox emits the full array including previously-set values, in options order", () => {
+    renderField(languagesField({ value: ["en"] }));
+    const deInput = capturedInputs.find(
+      (i) => i.kind === "boolean" && i.id === "kumiko-edit-languages-de",
+    );
+    expect(deInput?.kind).toBe("boolean");
+    if (deInput?.kind === "boolean") deInput.onChange(true);
+    expect(lastOnChange).toEqual(["en", "de"]);
+  });
+
+  test("unchecking a checkbox drops only that value, keeping options order", () => {
+    renderField(languagesField({ value: ["en", "de", "es"] }));
+    const deInput = capturedInputs.find(
+      (i) => i.kind === "boolean" && i.id === "kumiko-edit-languages-de",
+    );
+    if (deInput?.kind === "boolean") deInput.onChange(false);
+    expect(lastOnChange).toEqual(["en", "es"]);
+  });
+
+  test("select-all toggle shows 'Select all' when nothing is selected, and selects everything in options order", () => {
+    renderField(languagesField({ value: [] }));
+    expect(capturedButton?.children).toBe("Select all");
+    capturedButton?.onClick?.();
+    expect(lastOnChange).toEqual(["en", "de", "es"]);
+  });
+
+  test("select-all toggle flips to 'Deselect all' once everything is selected, and clears on click", () => {
+    renderField(languagesField({ value: ["en", "de", "es"] }));
+    expect(capturedButton?.children).toBe("Deselect all");
+    capturedButton?.onClick?.();
+    expect(lastOnChange).toEqual([]);
+  });
+
+  test("disabled (readOnly) disables every checkbox and the select-all toggle", () => {
+    renderField(languagesField({ readOnly: true }));
+    expect(capturedButton?.disabled).toBe(true);
+    for (const input of capturedInputs) {
+      expect(input.disabled).toBe(true);
+    }
+  });
+
+  test("columns and maxRows pass through to the Grid primitive", () => {
+    renderField(languagesField({ columns: 2, maxRows: 3 }));
+    expect(capturedGrid?.columns).toBe(2);
+    expect(capturedGrid?.maxRows).toBe(3);
+  });
+
+  test("omitting columns/maxRows keeps the default layout (no maxRows on the Grid)", () => {
+    renderField(languagesField());
+    expect(capturedGrid?.maxRows).toBeUndefined();
+  });
+});

package/src/components/multi-select-checkboxes.tsx

@@ -0,0 +1,93 @@
+import type { EditFieldViewModel } from "@cosmicdrift/kumiko-headless";
+import type { ReactNode } from "react";
+import { useTranslation } from "../i18n";
+import { usePrimitives } from "../primitives";
+
+export type MultiSelectCheckboxOption = {
+  readonly value: string;
+  readonly label: string;
+};
+
+export type MultiSelectCheckboxesProps = {
+  readonly field: EditFieldViewModel;
+  readonly id: string;
+  readonly options: readonly MultiSelectCheckboxOption[];
+  readonly value: readonly string[];
+  readonly onChange: (value: readonly string[]) => void;
+};
+
+// Renders MultiSelectFieldDef's `display: "checkboxes"` mode — every option
+// as a visible checkbox plus a select-all toggle, built purely from the
+// platform-neutral Primitives contract (Grid/GridCell/Field/Input kind
+// "boolean", the same primitive `case "boolean"` uses in render-field.tsx).
+// No renderer-web import here — this file must stay usable from Expo too.
+export function MultiSelectCheckboxes({
+  field,
+  id,
+  options,
+  value,
+  onChange,
+}: MultiSelectCheckboxesProps): ReactNode {
+  const { Grid, GridCell, Field, Input, Button } = usePrimitives();
+  const t = useTranslation();
+  const disabled = field.readOnly;
+  const selected = new Set(value);
+  const allSelected = options.length > 0 && options.every((opt) => selected.has(opt.value));
+
+  // Always emits in `field.options` order (MultiSelectFieldDef's documented
+  // ordering guarantee), never in click/selection order.
+  const emitOrdered = (next: ReadonlySet<string>): void => {
+    onChange(options.filter((opt) => next.has(opt.value)).map((opt) => opt.value));
+  };
+
+  const toggleOption = (optionValue: string, checked: boolean): void => {
+    const next = new Set(selected);
+    if (checked) {
+      next.add(optionValue);
+    } else {
+      next.delete(optionValue);
+    }
+    emitOrdered(next);
+  };
+
+  const toggleAll = (): void => {
+    emitOrdered(allSelected ? new Set() : new Set(options.map((opt) => opt.value)));
+  };
+
+  return (
+    <>
+      <Button
+        type="button"
+        variant="secondary"
+        size="sm"
+        disabled={disabled}
+        onClick={toggleAll}
+        testId={`${id}-select-all`}
+      >
+        {allSelected
+          ? t("kumiko.field.multiSelect.deselect-all")
+          : t("kumiko.field.multiSelect.select-all")}
+      </Button>
+      <Grid
+        columns={field.columns ?? 2}
+        testId={`${id}-checkboxes`}
+        {...(field.maxRows !== undefined && { maxRows: field.maxRows })}
+      >
+        {options.map((opt) => (
+          <GridCell key={opt.value}>
+            <Field id={`${id}-${opt.value}`} label={opt.label} layout="inline">
+              <Input
+                kind="boolean"
+                id={`${id}-${opt.value}`}
+                name={`${id}-${opt.value}`}
+                value={selected.has(opt.value)}
+                onChange={(checked) => toggleOption(opt.value, checked)}
+                disabled={disabled}
+              />
+            </Field>
+          </GridCell>
+        ))}
+      </Grid>
+    </>
+  );
+}

package/src/components/render-field.tsx

@@ -21,6 +21,7 @@ import { useQuery } from "../hooks/use-query";
 import { useLocale, useTranslation } from "../i18n";
 import { usePrimitives } from "../primitives";
 import { EmbeddedListField } from "./embedded-list-field";
+import { MultiSelectCheckboxes } from "./multi-select-checkboxes";
 import { ReferenceCreateDialog } from "./reference-create-dialog";
 
 // RenderField übersetzt ein EditFieldViewModel → Primitives-Baum.
@@ -514,6 +515,17 @@ function renderInput({
           ? rawOptions.map((value: string) => ({ value, label: labels[value] ?? value }))
           : rawOptions.map((value: string) => ({ value, label: value }));
       const arrayValue = Array.isArray(field.value) ? (field.value as readonly string[]) : [];
+      if (field.display === "checkboxes") {
+        return (
+          <MultiSelectCheckboxes
+            field={field}
+            id={id}
+            options={multiSelectOptions}
+            value={arrayValue}
+            onChange={(v) => onChange(v)}
+          />
+        );
+      }
       return (
         <Input
           kind="combobox"

package/src/i18n-defaults.ts

@@ -54,6 +54,8 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
       "{count} pasted row(s) were dropped (max row count reached).",
     "kumiko.field.embedded-list.paste-cells-unmatched":
       "{count} cell(s) had no matching option and were left unchanged.",
+    "kumiko.field.multiSelect.select-all": "Select all",
+    "kumiko.field.multiSelect.deselect-all": "Deselect all",
 
     "kumiko.list.search-placeholder": "Search…",
     "kumiko.list.empty.title": "No entries yet.",

package/src/primitives.tsx

@@ -739,6 +739,9 @@ export type GridProps = {
   readonly columns: number;
   readonly children: ReactNode;
   readonly testId?: string;
+  /** Rows visible before the grid becomes vertically scrollable. Omitted =
+   *  the grid grows with its content and never scrolls. */
+  readonly maxRows?: number;
 };
 
 /** Span-Wrapper für ein Kind innerhalb eines Grid. Web: `style={{gridColumn: span N}}`,