@twentyfirstmedia/ui-core 0.2.0 → 0.3.0

package/src/components/shell.tsx

@@ -1,5 +1,7 @@
 "use client";
 import * as React from "react";
+import { useStrings } from "../context.js";
+import { SHELL_STRINGS } from "../strings.js";
 import { Icon } from "../Icon.js";
 import { cx, reduced } from "../cx.js";
 import { Avatar } from "./foundation.js";
@@ -16,8 +18,9 @@ import type {
 } from "./types.js";
 
 export function TopBar(p: TopBarProps) {
+  const t = useStrings(SHELL_STRINGS);
   return (
-    <nav className="tf-topbar" aria-label="Main">
+    <nav className="tf-topbar" aria-label={t.mainNavigation}>
       {p.brand && (
         <span className="tf-brand">
           {p.brand}
@@ -88,8 +91,9 @@ function railBtn(it: RailItem, i: number) {
 }
 
 export function SideRail(p: SideRailProps) {
+  const t = useStrings(SHELL_STRINGS);
   return (
-    <aside className="tf-rail" aria-label="Tools">
+    <aside className="tf-rail" aria-label={t.tools}>
       <div className="tf-rail-group">{(p.top || []).map(railBtn)}</div>
       <div className="tf-rail-group">{(p.bottom || []).map((it, i) => railBtn(it, i + 3))}</div>
     </aside>
@@ -97,12 +101,13 @@ export function SideRail(p: SideRailProps) {
 }
 
 export function Dock(p: DockProps) {
+  const t = useStrings(SHELL_STRINGS);
   return (
     <div
       className={cx("tf-dock", p.surface && "tf-" + p.surface, p.className)}
       style={p.style}
       role="toolbar"
-      aria-label={p.label || "Quick actions"}
+      aria-label={p.label || t.quickActions}
     >
       {(p.items || []).map((it) => (
         <button

package/src/components/site.tsx

@@ -1,5 +1,7 @@
 "use client";
 import * as React from "react";
+import { useStrings } from "../context.js";
+import { SITE_STRINGS } from "../strings.js";
 import { useControlled } from "../hooks.js";
 import { cx } from "../cx.js";
 import { Icon } from "../Icon.js";
@@ -10,11 +12,12 @@ import type { AnnouncementBarProps, ChatLauncherProps, CookieConsentProps } from
 
 /* ── Site chrome: assistant launcher, cookie consent, announcement ── */
 export function ChatLauncher(p: ChatLauncherProps) {
+  const t = useStrings(SITE_STRINGS);
   const open = useControlled(p.open, false, p.onOpenChange);
   return (
     <div className={cx("tf-launch", open[0] && "open", p.inline && "inline")}>
       {open[0] && (
-        <div className="tf-launch-panel" role="dialog" aria-label={p.title || "Assistant"}>
+        <div className="tf-launch-panel" role="dialog" aria-label={p.title || t.assistant}>
           <div className="tf-launch-head">
             <AgentMark tint={p.tint || "lilac"} size={32} />
             <div
@@ -23,14 +26,14 @@ export function ChatLauncher(p: ChatLauncherProps) {
                 flex: 1,
               }}
             >
-              <b>{p.title || "Assistant"}</b>
+              <b>{p.title || t.assistant}</b>
               {p.context && <small>{p.context}</small>}
             </div>
             {p.headerAction}
             <IconButton
               icon="x"
               size="sm"
-              label="Close"
+              label={t.close}
               onClick={() => {
                 open[1](false);
               }}
@@ -43,7 +46,7 @@ export function ChatLauncher(p: ChatLauncherProps) {
       <button
         type="button"
         className="tf-launch-btn"
-        aria-label={open[0] ? "Close assistant" : p.title || "Open assistant"}
+        aria-label={open[0] ? t.closeAssistant : p.title || t.openAssistant}
         aria-expanded={open[0]}
         onClick={() => {
           open[1](!open[0]);
@@ -57,6 +60,7 @@ export function ChatLauncher(p: ChatLauncherProps) {
 }
 
 export function CookieConsent(p: CookieConsentProps) {
+  const t = useStrings(SITE_STRINGS);
   const more = React.useState(false),
     cats = React.useState(
       (p.categories || []).reduce<Record<string, boolean>>((a, c) => {
@@ -77,7 +81,7 @@ export function CookieConsent(p: CookieConsentProps) {
     <div
       className={cx("tf-cookie", p.inline && "inline")}
       role="dialog"
-      aria-label={p.title || "Privacy settings"}
+      aria-label={p.title || t.privacySettings}
     >
       <div
         className="tf-row"
@@ -94,15 +98,14 @@ export function CookieConsent(p: CookieConsentProps) {
             gap: 4,
           }}
         >
-          <b>{p.title || "Privacy settings"}</b>
+          <b>{p.title || t.privacySettings}</b>
           <p
             className="tf-card-desc"
             style={{
               margin: 0,
             }}
           >
-            {p.text ||
-              "We use cookies to run this site and, with your consent, to measure and improve it."}
+            {p.text || t.cookieText}
             {p.policy && <React.Fragment> {p.policy}</React.Fragment>}
           </p>
         </div>
@@ -121,7 +124,7 @@ export function CookieConsent(p: CookieConsentProps) {
                 {c.text && <small>{c.text}</small>}
               </div>
               {c.required ? (
-                <span className="tf-card-desc">{"Always on"}</span>
+                <span className="tf-card-desc">{t.alwaysOn}</span>
               ) : (
                 <Switch
                   checked={!!cats[0][c.id]}
@@ -144,7 +147,7 @@ export function CookieConsent(p: CookieConsentProps) {
               done(undefined);
             }}
           >
-            {"Save choice"}
+            {t.saveChoice}
           </Button>
         ) : (
           <Button
@@ -153,7 +156,7 @@ export function CookieConsent(p: CookieConsentProps) {
               more[1](true);
             }}
           >
-            {"Settings"}
+            {t.settings}
           </Button>
         )}
         <Button
@@ -162,14 +165,14 @@ export function CookieConsent(p: CookieConsentProps) {
             done(false);
           }}
         >
-          {"Only necessary"}
+          {t.onlyNecessary}
         </Button>
         <Button
           onClick={() => {
             done(true);
           }}
         >
-          {"Accept all"}
+          {t.acceptAll}
         </Button>
       </div>
     </div>
@@ -177,6 +180,7 @@ export function CookieConsent(p: CookieConsentProps) {
 }
 
 export function AnnouncementBar(p: AnnouncementBarProps) {
+  const t = useStrings(SITE_STRINGS);
   const shut = React.useState(false);
   if (shut[0]) return null;
   return (
@@ -188,7 +192,7 @@ export function AnnouncementBar(p: AnnouncementBarProps) {
         <button
           type="button"
           className="tf-announce-x"
-          aria-label="Dismiss"
+          aria-label={t.dismiss}
           onClick={() => {
             shut[1](true);
             p.onDismiss && p.onDismiss();

package/src/components/types.ts

@@ -21,23 +21,51 @@ export interface IconProps extends BaseProps {
   label?: string;
   className?: string;
 }
-export interface ButtonProps extends BaseProps {
+/**
+ * Native attributes `Button` and `IconButton` pass to their `<button>` (or, with `asChild`, to the
+ * child). Every other attribute of `<button>` (`data-*`, events such as `onKeyDown`, `ref` in
+ * React 19) is passed on as well; these are the ones worth knowing.
+ */
+export interface NativeButtonProps {
+  id?: string;
+  /** Form field name and value, sent with the form when this button submits it. */
+  name?: string;
+  value?: string;
+  /** The id of the form this button belongs to, when it sits outside it. */
+  form?: string;
+  title?: string;
+  tabIndex?: number;
+  autoFocus?: boolean;
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+  "aria-describedby"?: string;
+  /** For disclosure and menu triggers: whether what the button controls is open. */
+  "aria-expanded"?: boolean | "true" | "false";
+  "aria-controls"?: string;
+  "aria-haspopup"?: boolean | "true" | "false" | "menu" | "listbox" | "tree" | "grid" | "dialog";
+  /** For toggle buttons. */
+  "aria-pressed"?: boolean | "true" | "false" | "mixed";
+  "aria-current"?: boolean | "true" | "false" | "page" | "step" | "location" | "date" | "time";
+}
+export interface ButtonProps extends BaseProps, NativeButtonProps {
   variant?: "primary" | "secondary" | "soft" | "ghost" | "danger" | "danger-solid";
   size?: "md" | "sm";
   icon?: IconName;
   iconRight?: IconName;
   disabled?: boolean;
-  type?: "button" | "submit";
+  type?: "button" | "submit" | "reset";
   onClick?: (e: MouseEvent<HTMLButtonElement>) => void;
   children?: ReactNode;
   /** Render the single child element (a link, a router Link) with the button's look instead of a <button>. */
   asChild?: boolean;
 }
-export interface IconButtonProps extends BaseProps {
+export interface IconButtonProps extends BaseProps, NativeButtonProps {
   icon: IconName;
+  /** Accessible name and tooltip (`aria-label` and `title`); `aria-label` or `title` override them. */
   label: string;
   variant?: "soft" | "solid" | "outline" | "ghost";
   size?: "sm" | "md" | "lg";
+  type?: "button" | "submit" | "reset";
   onClick?: (e: MouseEvent<HTMLButtonElement>) => void;
   disabled?: boolean;
   /** Render the single child element (a link) with the button's look; the icon is placed inside it. */
@@ -107,6 +135,8 @@ export interface TextareaProps extends FieldProps, BaseProps {
 }
 export interface SearchFieldProps extends BaseProps {
   placeholder?: string;
+  /** Accessible name (default: the placeholder, or "Search"). */
+  label?: string;
   shortcut?: string;
   value?: string;
   onChange?: (e: ChangeEvent<HTMLInputElement>) => void;
@@ -298,8 +328,17 @@ export interface BreadcrumbProps extends BaseProps {
   items: string[];
 }
 export interface PaginationProps extends BaseProps {
+  /** Number of pages. */
   total: number;
+  /**
+   * The current page (1-based). Controlled together with `onChange`; without `onChange` it is
+   * only the start page, as in earlier versions (prefer `defaultPage` for that).
+   */
   page?: number;
+  /** Start page when uncontrolled (default 1). */
+  defaultPage?: number;
+  /** A page was picked (previous, next or a number); receives the new 1-based page. */
+  onChange?: (page: number) => void;
 }
 export interface AppShellProps extends BaseProps {
   active?: string;
@@ -607,6 +646,7 @@ export interface FormFieldProps extends BaseProps {
   children?: ReactNode;
 }
 export interface TextFieldProps extends Omit<FormFieldProps, "children"> {
+  /** Input type (`"text"` by default): `"email"`, `"number"`, `"tel"`, `"url"`, `"password"` … */
   type?: string;
   icon?: IconName;
   suffix?: ReactNode;
@@ -614,7 +654,23 @@ export interface TextFieldProps extends Omit<FormFieldProps, "children"> {
   defaultValue?: string;
   placeholder?: string;
   disabled?: boolean;
+  readOnly?: boolean;
   autoComplete?: string;
+  autoFocus?: boolean;
+  /** Smallest value for `type="number"`, `"date"` and the like (native `min`). */
+  min?: number | string;
+  /** Largest value (native `max`). */
+  max?: number | string;
+  /** Step between valid values (native `step`), e.g. `1` for whole numbers or `"any"`. */
+  step?: number | string;
+  /** Fewest characters (native `minlength`). */
+  minLength?: number;
+  /** Most characters (native `maxlength`). */
+  maxLength?: number;
+  /** Pattern the value must match (native `pattern`). */
+  pattern?: string;
+  /** Virtual keyboard on touch devices (native `inputmode`), e.g. `"numeric"` or `"decimal"`. */
+  inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search";
   onChange?: (e: ChangeEvent<HTMLInputElement>) => void;
   onBlur?: (e: ChangeEvent<HTMLInputElement>) => void;
 }
@@ -720,13 +776,34 @@ export interface UploadFile {
   id: string;
   name: string;
   size: number;
+  /** Upload progress 0–100: a bar while below 100, "uploaded" at 100. */
   progress: number;
+  /** The picked or dropped file (set by FileDrop for files it adds). */
+  file?: File;
 }
 export interface FileDropProps extends BaseProps {
+  /** The listed files (controlled); set `progress` per file to show real upload progress. */
   files?: UploadFile[];
+  /** The list changed: files added (with their `file`) or removed. */
   onChange?: (f: UploadFile[]) => void;
+  /**
+   * The person picked or dropped files: the real `File` objects, after `accept` and `multiple`.
+   * Upload them yourself. To show progress, control `files` and set each `progress`; an
+   * uncontrolled list shows them with their size only.
+   */
+  onFiles?: (files: File[]) => void;
+  /** Dropped files that do not match `accept` (show an inline Alert). */
+  onReject?: (files: File[]) => void;
+  /** A listed file was removed or its upload cancelled. */
+  onRemove?: (f: UploadFile) => void;
+  /**
+   * Animate made-up progress for added files, as a demo of the look. Default: on without
+   * `onFiles` (as before), off with it.
+   */
+  simulateProgress?: boolean;
   title?: string;
   hint?: string;
+  /** Accepted types, as for `<input type="file">` ("image/*,.pdf"); also checked on drop. */
   accept?: string;
   multiple?: boolean;
 }
@@ -1114,6 +1191,8 @@ export interface PlanCardProps extends BaseProps {
   flag?: string;
   current?: boolean;
   cta?: string;
+  /** Disable the button, e.g. while a checkout starts or when the plan cannot be picked. */
+  disabled?: boolean;
   onPick?: () => void;
 }
 
@@ -2108,6 +2187,17 @@ export interface ImageVariantsProps extends BaseProps {
   tint?: Tint;
   actions?: ReactNode;
 }
+/** `referrerPolicy` values of `<img>`. */
+export type ImageReferrerPolicy =
+  | ""
+  | "no-referrer"
+  | "no-referrer-when-downgrade"
+  | "origin"
+  | "origin-when-cross-origin"
+  | "same-origin"
+  | "strict-origin"
+  | "strict-origin-when-cross-origin"
+  | "unsafe-url";
 export interface GalleryItem {
   src?: string;
   alt?: string;
@@ -2117,6 +2207,13 @@ export interface GalleryItem {
 }
 export interface GalleryProps extends BaseProps {
   items: GalleryItem[];
+  /**
+   * Loading of the main image: `"lazy"` (default) waits until the gallery is near the viewport;
+   * use `"eager"` for a gallery at the top of the page. Thumbnails always load lazily.
+   */
+  loading?: "lazy" | "eager";
+  /** `referrerPolicy` of every image, e.g. `"no-referrer"` for photos from other hosts. */
+  referrerPolicy?: ImageReferrerPolicy;
   start?: number;
   ratio?: string;
   thumbs?: boolean;
@@ -2136,6 +2233,17 @@ export interface BeforeAfterProps extends BaseProps {
   ratio?: string;
   beforeLabel?: string;
   afterLabel?: string;
+  /** Accessible name of the slider (default "Compare before and after"). */
+  label?: string;
+  /**
+   * What screen readers hear for a position (0–100, the share of "before"). Default:
+   * "Before 40%, After 60%", with your `beforeLabel`/`afterLabel`.
+   */
+  valueText?: (percent: number) => string;
+  /** Loading of both images (default `"lazy"`). */
+  loading?: "lazy" | "eager";
+  /** `referrerPolicy` of both images. */
+  referrerPolicy?: ImageReferrerPolicy;
 }
 
 /* ── Kit 5: real estate ── */