@12-apps/ui 6.7.0 → 6.9.0

package/src/components/utility/InstallPrompt/InstallPrompt.tsx

@@ -8,6 +8,7 @@ import React from 'react';
 import { installPromptStyles } from './InstallPrompt.styles';
 import type { InstallPlatform, InstallPromptProps } from './InstallPrompt.types';
 import { usePwaInstall } from './usePwaInstall';
+import type { InstallPromptCopy } from '../../../copy';
 
 const StyledInstallPrompt = styled(Box)(({ theme }) => installPromptStyles(theme));
 
@@ -20,9 +21,10 @@ const testIdFor = (base: string | undefined, suffix: string) =>
  * be a control that does nothing when pressed.
  */
 const IosInstructions: React.FC<{
+  copy: InstallPromptCopy;
   instructions?: React.ReactNode;
   dataTestId?: string;
-}> = ({ instructions, dataTestId }) => (
+}> = ({ copy, instructions, dataTestId }) => (
   <Typography
     className="install-prompt-description"
     variant="body2"
@@ -32,20 +34,22 @@ const IosInstructions: React.FC<{
   >
     {instructions ?? (
       <>
-        Tap <IosShare fontSize="small" aria-label="Share" /> then &quot;Add to Home Screen&quot;
+        {copy.iosTapBefore} <IosShare fontSize="small" aria-label={copy.shareLabel} />{' '}
+        {copy.iosTapAfter}
       </>
     )}
   </Typography>
 );
 
 const InstallPromptBody: React.FC<{
+  copy: InstallPromptCopy;
   icon?: React.ReactNode;
   title: string;
   description?: string;
   iosInstructions?: React.ReactNode;
   platform: InstallPlatform;
   dataTestId?: string;
-}> = ({ icon, title, description, iosInstructions, platform, dataTestId }) => (
+}> = ({ copy, icon, title, description, iosInstructions, platform, dataTestId }) => (
   <>
     <Box className="install-prompt-icon" aria-hidden="true">
       {icon ?? <InstallMobile />}
@@ -73,7 +77,7 @@ const InstallPromptBody: React.FC<{
       )}
 
       {platform === 'ios' && (
-        <IosInstructions instructions={iosInstructions} dataTestId={dataTestId} />
+        <IosInstructions copy={copy} instructions={iosInstructions} dataTestId={dataTestId} />
       )}
     </Box>
   </>
@@ -118,17 +122,17 @@ const InstallPromptActions: React.FC<{
  * browser with no install route at all — so it is safe to mount unconditionally
  * in a layout rather than gating it at the call site.
  *
- * The copy defaults to English and every string is a prop: this package stays
- * locale-neutral and the consuming app supplies its own wording.
+ * Every string is REQUIRED host config (`copy`): this package stays
+ * locale-neutral and the consuming app supplies its own wording. There is no
+ * English default to fall through to, so a missing word is a typecheck failure
+ * rather than an English sentence in a pt-BR store.
  */
 export const InstallPrompt = React.forwardRef<HTMLDivElement, InstallPromptProps>(
   (
     {
-      title = 'Install this app',
+      copy,
       description,
-      installLabel = 'Install',
       iosInstructions,
-      dismissLabel = 'Dismiss install prompt',
       icon,
       onInstall,
       onDismiss,
@@ -163,13 +167,14 @@ export const InstallPrompt = React.forwardRef<HTMLDivElement, InstallPromptProps
         ref={ref}
         className={className}
         role="region"
-        aria-label={title}
+        aria-label={copy.title}
         data-testid={dataTestId}
         {...props}
       >
         <InstallPromptBody
           icon={icon}
-          title={title}
+          copy={copy}
+          title={copy.title}
           description={description}
           iosInstructions={iosInstructions}
           platform={platform}
@@ -178,8 +183,8 @@ export const InstallPrompt = React.forwardRef<HTMLDivElement, InstallPromptProps
 
         <InstallPromptActions
           platform={platform}
-          installLabel={installLabel}
-          dismissLabel={dismissLabel}
+          installLabel={copy.installLabel}
+          dismissLabel={copy.dismissLabel}
           onInstallClick={handleInstall}
           onDismissClick={handleDismiss}
           dataTestId={dataTestId}

package/src/components/utility/InstallPrompt/InstallPrompt.types.ts

@@ -1,5 +1,7 @@
 import type { ReactNode } from 'react';
 
+import type { InstallPromptCopy } from '../../../copy';
+
 /**
  * The Chromium-only event that makes a PWA installable from inside the page.
  * It is NOT in TypeScript's DOM lib because it is not a standard: Safari and
@@ -70,16 +72,16 @@ export interface PwaInstallState {
 }
 
 export interface InstallPromptProps {
-  /** Headline text. */
-  title?: string;
+  /**
+   * Every word this prompt renders. REQUIRED: this package ships no default
+   * copy, and the iOS half is a GESTURE instruction — a shopper who cannot
+   * read it cannot install the app at all.
+   */
+  copy: InstallPromptCopy;
   /** Supporting line under the title. */
   description?: string;
-  /** Label for the install button (Chromium only). */
-  installLabel?: string;
-  /** Replaces the built-in iOS Share → Add to Home Screen wording. */
+  /** Replaces the built-in iOS Share → Add to Home Screen wording outright. */
   iosInstructions?: ReactNode;
-  /** Accessible label for the dismiss button. */
-  dismissLabel?: string;
   /** Leading icon. Defaults to an install glyph. */
   icon?: ReactNode;
   /** Called with the outcome after the native prompt resolves. */

package/src/copy/data-display.ts

@@ -0,0 +1,60 @@
+/**
+ * The display family's words — the lightbox and map viewers, the carousel,
+ * the timing diagram, and the shared empty/error states.
+ *
+ * Split out of `copy.ts`, which is a barrel over this folder: one file
+ * listing every family is the file that grows on every port, and it stopped
+ * fitting the 400-line budget the rest of this package holds itself to.
+ */
+
+/**
+ * The lightbox's controls, every one of them a glyph with no text.
+ *
+ * So this object IS what a screen-reader user hears for the whole viewer —
+ * which is why it shipped as English literals for so long without anyone
+ * noticing: the sighted path renders identically either way.
+ */
+export interface LightboxCopy {
+  close: string;
+  previous: string;
+  next: string;
+  zoomIn: string;
+  zoomOut: string;
+  resetZoom: string;
+  /** The slideshow toggle, in its two states. */
+  play: string;
+  pause: string;
+}
+
+/** The map preview's control bar — same shape, same reason, as the lightbox. */
+export interface MapPreviewCopy {
+  zoomIn: string;
+  zoomOut: string;
+  center: string;
+  mapType: string;
+  fullscreen: string;
+  search: string;
+}
+
+/** The carousel's two arrows, which carry a glyph and nothing else. */
+export interface CarouselCopy {
+  previous: string;
+  next: string;
+}
+
+/** The request-timing diagram's own two strings. */
+export interface TimingDiagramCopy {
+  regionLabel: string;
+  heading: string;
+}
+
+export interface DataStateCopy {
+  /** No rows at all — distinct from "no rows for these filters". */
+  empty: string;
+  loading: string;
+  /** The infinite scroller reached the end. */
+  endOfList: string;
+  /** An alert's and a banner's dismiss, neither of which has a visible label. */
+  dismissAlert: string;
+  dismissBanner: string;
+}

package/src/copy/feedback.ts

@@ -0,0 +1,39 @@
+/**
+ * The feedback family's words — the tutorial overlay and the app chrome it
+ * points at.
+ *
+ * Split out of `copy.ts`, which is a barrel over this folder: one file
+ * listing every family is the file that grows on every port, and it stopped
+ * fitting the 400-line budget the rest of this package holds itself to.
+ */
+
+/**
+ * The states a data surface can be in with nothing to draw, and the dismiss
+ * every banner-like surface carries.
+ *
+ * One object rather than six, because these are the same four sentences the
+ * table, the grid, the async container, the hover card and the infinite
+ * scroller each rendered their own copy of.
+ */
+/** The guided tour's four controls, and the toast/modal chrome around it. */
+export interface TutorialCopy {
+  skip: string;
+  previous: string;
+  next: string;
+  restart: string;
+}
+
+/** Chrome that carries a glyph and no text, across several small surfaces. */
+export interface ChromeCopy {
+  /** The toast's dismiss, and the stacked modal's step-back arrow. */
+  dismissToast: string;
+  goBack: string;
+  /** A dashboard panel's close, and a tab's. */
+  closePanel: string;
+  closeTab: string;
+  /** The scroll region itself, and the button that returns to its top. */
+  scrollRegion: string;
+  scrollToTop: string;
+  /** The share affordance in the install prompt. */
+  share: string;
+}

package/src/copy/form.ts

@@ -0,0 +1,154 @@
+/**
+ * The form family's words. The largest group, and the one where the leak was
+ * least visible: half of these are tooltips and announcements that only a
+ * screen reader ever receives, so a language pass over the rendered text
+ * walked straight past them.
+ *
+ * Split out of `copy.ts`, which is a barrel over this folder: one file
+ * listing every family is the file that grows on every port, and it stopped
+ * fitting the 400-line budget the rest of this package holds itself to.
+ */
+
+/**
+ * The address field's three sentences. Two of them are about Google Maps
+ * failing to arrive — read by the shopper while the field is unusable, which
+ * is the worst moment to be spoken to in the wrong language.
+ */
+export interface AddressAutocompleteCopy {
+  /** Placeholder while the Maps script is still loading. */
+  loadingMaps: string;
+  /** The alert shown when the script never arrived. */
+  mapsLoadFailed: string;
+  /** The pin button's tooltip, which is also its accessible name. */
+  useCurrentLocation: string;
+}
+
+/** What an `Autocomplete` renders that is not one of the host's own options. */
+export interface AutocompleteCopy {
+  /** The two rows shown in place of options: fetching, and came back empty. */
+  loading: string;
+  noResults: string;
+  /** The input's own prompt, used when the host does not override it. */
+  placeholder: string;
+}
+
+/**
+ * The code editor's chrome. Every one of the four action buttons is a glyph
+ * whose tooltip IS its accessible name, so this object is the whole of what a
+ * screen reader reads out for the toolbar.
+ */
+export interface CodeEditorCopy {
+  /** Shown while the editor bundle is still arriving. */
+  loading: string;
+  /** The badge beside the language when the buffer cannot be edited. */
+  readOnly: string;
+  /** The format button's tooltip. Carries its own keyboard shortcut. */
+  formatCode: string;
+  /** The wrap toggle, in its two states. */
+  enableWrap: string;
+  disableWrap: string;
+  /** The copy button, before and after it has been pressed. */
+  copyToClipboard: string;
+  copied: string;
+  /** The fullscreen toggle, in its two states. */
+  enterFullscreen: string;
+  exitFullscreen: string;
+}
+
+/** The five strength bands, weakest first. */
+export interface PasswordStrengthBandCopy {
+  veryWeak: string;
+  weak: string;
+  fair: string;
+  good: string;
+  strong: string;
+}
+
+/**
+ * One line per requirement. `minLength` takes the configured count because the
+ * number is part of the sentence, and a language may not put it where English
+ * does.
+ */
+export interface PasswordRequirementCopy {
+  minLength(count: number): string;
+  uppercase: string;
+  lowercase: string;
+  numbers: string;
+  special: string;
+}
+
+/** Everything the password meter renders. */
+export interface PasswordStrengthCopy {
+  /** The three headings: the meter, the checklist, the tips. */
+  strengthHeading: string;
+  requirementsHeading: string;
+  suggestionsHeading: string;
+  bands: PasswordStrengthBandCopy;
+  /** The checklist rows, and the tip shown for each unmet one. */
+  requirements: PasswordRequirementCopy;
+  suggestions: PasswordRequirementCopy;
+}
+
+/**
+ * The rich-text toolbar. Ten glyph buttons, every one of them named ONLY by
+ * its tooltip — so this object is the whole of what a screen reader reads out
+ * for the editor's controls.
+ */
+export interface RichEditorToolbarCopy {
+  bold: string;
+  italic: string;
+  underline: string;
+  bulletList: string;
+  numberedList: string;
+  quote: string;
+  code: string;
+  insertLink: string;
+  textColor: string;
+  backgroundColor: string;
+  /** The browser prompt the link button opens, asking for the URL. */
+  linkPrompt: string;
+}
+
+/**
+ * What the phone field says on its own account. The picker's name is the whole
+ * of what a screen reader gets for a control rendered as a flag and a dial
+ * code, and the invalid sentence is read by the shopper at the checkout.
+ */
+export interface PhoneInputCopy {
+  /** The country picker's accessible name. */
+  selectCountry: string;
+  /**
+   * The number does not validate for the chosen country. Takes the country's
+   * own name, because a language may not place it where English does.
+   */
+  invalidNumber(countryName: string): string;
+  /** Stands in for the country's name before one has been resolved. */
+  unknownCountry: string;
+}
+
+/**
+ * What the upload control says beyond the host's own button label. Three of
+ * the four are announcements a screen reader reads and nothing renders — which
+ * is why they stayed English through every language pass.
+ */
+export interface UploadButtonCopy {
+  /** The control's own label, used when the host does not override it. */
+  buttonLabel: string;
+  /** The dropzone's second line, under the host's own label. */
+  dropzoneHint: string;
+  /**
+   * The dropzone's accessible name, which prefixes the host's label — it says
+   * what KIND of control this is before saying what it uploads.
+   */
+  dropzoneRole(label: string): string;
+  /** The button's label while an upload is in flight. */
+  uploading: string;
+  /** Announced when a dragged file is over the zone and would be accepted. */
+  dropReady: string;
+  /** The caption under the progress bar. */
+  percentUploaded(percent: number): string;
+  /** The same progress, announced rather than shown. */
+  uploadInProgress(percent: number): string;
+  /** The component's own error, announced. Takes the message it wraps. */
+  errorAnnouncement(message: string): string;
+}

package/src/copy/layout.ts

@@ -0,0 +1,18 @@
+/**
+ * The layout family's words — the filter shell a grid mounts around itself.
+ *
+ * Split out of `copy.ts`, which is a barrel over this folder: one file
+ * listing every family is the file that grows on every port, and it stopped
+ * fitting the 400-line budget the rest of this package holds itself to.
+ */
+
+export interface TableFilterCopy {
+  /** Drop every applied filter, and the keyword box's own clear. */
+  clearAllFilters: string;
+  clearKeyword: string;
+  /** A numeric range whose maximum is below its minimum. */
+  invalidRange: string;
+  /** The two free-text bounds, which carry no visible label of their own. */
+  rangeMin: string;
+  rangeMax: string;
+}

package/src/copy/navigation.ts

@@ -0,0 +1,25 @@
+/**
+ * The navigation family's words — the command palette and the breadcrumb
+ * trail.
+ *
+ * Split out of `copy.ts`, which is a barrel over this folder: one file
+ * listing every family is the file that grows on every port, and it stopped
+ * fitting the 400-line budget the rest of this package holds itself to.
+ */
+
+/** The command palette's footer hints and its empty state. */
+export interface CommandPaletteCopy {
+  /** The three keyboard hints, each a chip in the footer. */
+  execute: string;
+  navigate: string;
+  close: string;
+  /** The recent-commands group, and the nudge under "nothing found". */
+  recent: string;
+  tryAnotherTerm: string;
+}
+
+/** The breadcrumb's overflow control, in its two spellings. */
+export interface BreadcrumbCopy {
+  showMore: string;
+  moreItems: string;
+}

package/src/copy/shared.ts

@@ -0,0 +1,122 @@
+/**
+ * Words shared by more than one family: the guided-section chrome, the
+ * confirm dialog behind a destructive action, the category picker and the CEP
+ * lookup.
+ *
+ * Split out of `copy.ts`, which is a barrel over this folder: one file
+ * listing every family is the file that grows on every port, and it stopped
+ * fitting the 400-line budget the rest of this package holds itself to.
+ */
+
+export interface SectionOnboardingCopy {
+  /** The button that begins the guided section. */
+  start: string;
+  /** The reveal toggle in the configured state, and its collapsed twin. */
+  edit: string;
+  collapse: string;
+}
+
+export interface ConfirmActionCopy {
+  /** The dismiss button every confirmation shares. */
+  cancel: string;
+  /** Shown when the action fails and the caller supplied no reason. */
+  defaultError: string;
+  /**
+   * The fallback body when the caller names no entity.
+   *
+   * A caller that DOES name one gets the host's own sentence — this package
+   * never guesses a noun for someone else's rows.
+   */
+  irreversible: string;
+  /**
+   * The typed-confirmation prompt, naming the exact word that unlocks the
+   * button. A function because where that word sits in the sentence, and how
+   * it is quoted, is the translator's call.
+   */
+  typeToConfirm(expected: string): string;
+}
+
+export interface CategorySelectCopy {
+  /**
+   * What categories are FOR, in the host's own terms.
+   *
+   * This used to read "Categorias organizam o cardápio e os filtros da loja" —
+   * a restaurant's menu, hard-coded into a generic picker. A host selling
+   * insurance policies got told about its cardápio.
+   */
+  purpose: string;
+  clearSelection: string;
+  /**
+   * The quick actions above the tree. Each toggles as a PAIR, and each label
+   * says what pressing it will do rather than what state the list is in — so a
+   * translator needs both halves, not one plus a negation.
+   */
+  selectAll: string;
+  deselectAll: string;
+  expandAll: string;
+  collapseAll: string;
+  /**
+   * ONE row's chevron, in its two states — a glyph button inside the row
+   * button, so this pair is the whole of what a screen reader reads for it.
+   * The category's own name is appended by the caller.
+   */
+  expandCategory(name: string): string;
+  collapseCategory(name: string): string;
+  /**
+   * What the closed control invites, and it differs by mode: picking ONE
+   * category is a move, picking several is a filter. Both were pt-BR defaults
+   * behind an optional prop, which is the arrangement this port removes.
+   */
+  placeholderSingle: string;
+  placeholderMulti: string;
+  /** The empty state, when the host has no categories at all. */
+  emptyTitle: string;
+  createCategory: string;
+  /**
+   * The search found nothing.
+   *
+   * Two of the four interpolate the term typed, so they are functions rather
+   * than strings with a placeholder to substitute: where the term sits in the
+   * sentence is the translator's call, not ours.
+   */
+  noResults: {
+    title: (query: string) => string;
+    hint: string;
+    clearSearch: string;
+    create: (query: string) => string;
+  };
+  /**
+   * The panel's two footers.
+   *
+   * `selectedCount` is a function because Portuguese agrees the participle with
+   * the count and English does not — the shape has to let a translator decide
+   * the whole sentence, not fill a slot in ours.
+   */
+  /** The search box above the list, and the chips beneath it. */
+  search: {
+    /** Two placeholders: a single-select picker offers no subcategories. */
+    placeholderSingle: string;
+    placeholderMulti: string;
+    clear: string;
+    removeChip(label: string): string;
+    /** The tray above the list, counting what is already picked. */
+    pinnedLabel(count: number): string;
+  };
+  footer: {
+    selectedCount(count: number): string;
+    clear: string;
+    /** The primary button, which reads `close` while the draft is unchanged. */
+    apply: string;
+    close: string;
+    /** The single-select footer: what to do, and the way out. */
+    singleHint: string;
+    cancel: string;
+  };
+}
+
+export interface CepFieldCopy {
+  loading: string;
+  found: string;
+  /** Keyed to match `CepLookupStatus` exactly, so the lookup can index it. */
+  notfound: string;
+}

package/src/copy/utility.ts

@@ -0,0 +1,36 @@
+/**
+ * The utility family's words — the install prompt and the account card.
+ *
+ * Split out of `copy.ts`, which is a barrel over this folder: one file
+ * listing every family is the file that grows on every port, and it stopped
+ * fitting the 400-line budget the rest of this package holds itself to.
+ */
+
+/**
+ * The install prompt's own words. Two of the three surfaces here are iOS-only:
+ * Safari has no programmatic install, so the component explains the gesture
+ * instead of offering a button.
+ */
+export interface InstallPromptCopy {
+  /** Headline, and the Chromium install button. */
+  title: string;
+  installLabel: string;
+  /** The dismiss button's accessible name — it renders as a bare cross. */
+  dismissLabel: string;
+  /**
+   * The iOS instruction, split around the Share glyph that sits INSIDE the
+   * sentence: "Tap [share] then Add to Home Screen". Two halves rather than
+   * one string because the glyph's position is part of the sentence and a
+   * language may not put it where English does. A host wanting a different
+   * shape entirely passes `iosInstructions` and replaces the whole node.
+   */
+  iosTapBefore: string;
+  iosTapAfter: string;
+  /** The Share glyph's accessible name, mid-sentence. */
+  shareLabel: string;
+}
+
+/** The account card's one action. */
+export interface UserAvatarCopy {
+  signOut: string;
+}