@12-apps/storage 2.3.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/storage",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "Image uploads that land at YOUR OWN ORIGIN, never at the bucket (12-20). Isomorphic core (format allowlist, upload ceiling, object-key grammar, rendition set, refusal taxonomy, wire schemas), host-mounted backend surface (./server: createApiStorage, the local-disk driver, the image-pipeline port, the orphan reclaim), Hono adapter (./hono), the S3-compatible driver behind its own subpath (./s3) and the bound picker + upload hook (./react). Standardized adoption contract in ADOPTING.md.",
   "exports": {
@@ -43,11 +43,12 @@
     }
   },
   "dependencies": {
-    "@12-apps/ui": "^6.4.0",
+    "@12-apps/ui": "^6.9.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
+    "@12-apps/i18n": "^1.0.0",
     "@12-apps/typescript-config": "^1.20.1",
     "@12-apps/wiring": "^1.10.0",
     "@aws-sdk/client-s3": "^3.703.0",

package/src/en-US.ts

@@ -0,0 +1,30 @@
+import type { StorageMessageContext, StorageMessages } from './problems';
+
+/**
+ * The en-US pack — a NAMED factory a host passes by hand
+ * (`messages: EN_US_STORAGE_MESSAGES`), never a default. The filename is what
+ * exempts this file from the copy-portability gate, as `pt-BR.ts` beside it is
+ * exempt.
+ *
+ * `limit` is interpolated rather than hard-coded, for the reason the pt-BR pack
+ * gives: a host that raises `maxBytes` must not end up with a message naming
+ * the old number, which is the single commonest way this kind of copy goes
+ * stale. A translation that inlined the number would reintroduce exactly that.
+ */
+export function EN_US_STORAGE_MESSAGES(context: StorageMessageContext): StorageMessages {
+  return {
+    invalid_base64: 'That image is not correctly base64-encoded.',
+    empty_file: 'That image is empty.',
+    file_too_large: `That image is larger than the ${context.limit} limit.`,
+    content_mismatch:
+      'The image contents do not match the format you declared. Send a PNG, JPEG, WebP or GIF.',
+    unsupported_content_type: 'Unsupported format. Send a PNG, JPG, WebP or GIF.',
+    image_unreadable: 'That image could not be read — the file appears to be corrupted.',
+    image_dimensions_too_large: 'That image is too large in dimensions to process.',
+    storage_not_configured: 'Image storage has not been set up for this store yet.',
+    storage_unavailable: 'That image could not be saved right now. Try again in a moment.',
+  };
+}
+
+/** The 401 the mounted router answers when the host resolves no actor. */
+export const EN_US_STORAGE_UNAUTHENTICATED = 'Not authenticated.';

package/src/index.ts

@@ -76,6 +76,8 @@ export {
   type StorageProblem,
 } from './problems';
 export { PT_BR_STORAGE_MESSAGES, PT_BR_STORAGE_UNAUTHENTICATED } from './pt-BR';
+export { EN_US_STORAGE_MESSAGES, EN_US_STORAGE_UNAUTHENTICATED } from './en-US';
+export { STORAGE_MESSAGES, STORAGE_UNAUTHENTICATED } from './locales';
 
 export {
   imageSources,

package/src/locales.ts

@@ -0,0 +1,31 @@
+import { EN_US_STORAGE_MESSAGES, EN_US_STORAGE_UNAUTHENTICATED } from './en-US';
+import type { StorageMessageContext, StorageMessages } from './problems';
+import { PT_BR_STORAGE_MESSAGES, PT_BR_STORAGE_UNAUTHENTICATED } from './pt-BR';
+
+/**
+ * Both languages, keyed by tag — what a host hands to `@12-apps/i18n` when the
+ * reader's language is a property of the request rather than of the deployment.
+ *
+ * The pack holds FACTORIES rather than tables, because that is what this
+ * package's copy already is: `limit` is interpolated so a host that raises
+ * `maxBytes` cannot end up with a message naming the old number. `localeCopy`
+ * therefore hands back a factory, and the host calls it with its context:
+ *
+ * ```ts
+ * const messages = localeCopy(STORAGE_MESSAGES)({ locale })({ limit });
+ * ```
+ *
+ * `LocalePack` is mirrored here rather than imported so the package stays
+ * liftable into a repo that has never heard of `@12-apps/i18n`.
+ */
+type LocalePack<T> = { readonly 'pt-BR': T; readonly 'en-US': T };
+
+export const STORAGE_MESSAGES = {
+  'pt-BR': PT_BR_STORAGE_MESSAGES,
+  'en-US': EN_US_STORAGE_MESSAGES,
+} as const satisfies LocalePack<(context: StorageMessageContext) => StorageMessages>;
+
+export const STORAGE_UNAUTHENTICATED = {
+  'pt-BR': PT_BR_STORAGE_UNAUTHENTICATED,
+  'en-US': EN_US_STORAGE_UNAUTHENTICATED,
+} as const satisfies LocalePack<string>;

package/src/react/create-web-storage.tsx

@@ -86,6 +86,7 @@ export function createWebStorage(config: WebStorageConfig): WebStorage {
           onChange={setImageKey}
           label={messages.fieldLabel}
           removeLabel={messages.fieldRemove}
+          uploadCopy={messages.field}
           helperText={messages.fieldHelper}
         />
       </Stack>

package/src/react/en-US.ts

@@ -0,0 +1,49 @@
+import type { WebStorageMessageContext, WebStorageMessages } from './failures';
+
+/**
+ * The en-US pack — a NAMED factory a host passes by hand, never a default.
+ * `limit` is interpolated for the same reason the server pack does it: a host
+ * that raises the ceiling must not end up with copy naming the old number.
+ */
+export function EN_US_WEB_STORAGE_MESSAGES(
+  context: WebStorageMessageContext,
+): WebStorageMessages {
+  return {
+    forbidden: 'Your account may not upload images for this store.',
+    unsupported_content_type: 'Unsupported format. Send a PNG, JPG, WebP or GIF.',
+    file_too_large: `That image is too large. The limit is ${context.limit}.`,
+    invalid_key: 'That image could not be found.',
+    not_found: 'That image is no longer available.',
+    session_expired: 'Your session has expired. Sign in again and repeat the upload.',
+    transport: 'Could not reach the server. Check your connection and try again.',
+    empty_file: 'Empty file (0 bytes). Pick the image again.',
+    file_too_large_upfront: ({ size, limit }) =>
+      `That image is too large: ${size}. The limit is ${limit} — shrink it and try again.`,
+    unknown_content_type: 'Could not identify the file type. Send a PNG, JPG or WebP.',
+    unsupported_content_type_upfront: ({ contentType }) =>
+      `Unsupported format (${contentType}). Send a PNG, JPG, WebP or GIF.`,
+    missing_key: 'The server accepted the image but returned no key. Try again.',
+    upload_failed_http: ({ status, detail }) =>
+      `Could not upload that image (HTTP ${status}${detail}). Try again in a moment.`,
+    upload_failed: 'Uploading that image failed. Try again in a moment.',
+
+    pageTitle: 'Store images',
+    pageIntro: `Send a PNG, JPG, WebP or GIF of up to ${context.limit}.`,
+    fieldLabel: 'Product photo',
+    fieldHelper: 'The image is resized in the browser before it is sent.',
+    fieldRemove: 'Remove image',
+    field: {
+      // `buttonLabel` is never read here — `ImageField` overrides it with
+      // `fieldLabel`. It is still answered, because the type is the whole of
+      // what `UploadButton` may render and a partial answer is not a pack.
+      buttonLabel: 'Product photo',
+      dropzoneHint: 'Drop the image here, or click to choose one',
+      dropzoneRole: (label) => `Image upload area. ${label}`,
+      uploading: 'Uploading…',
+      dropReady: 'Image ready to drop',
+      percentUploaded: (percent) => `${percent}% uploaded`,
+      uploadInProgress: (percent) => `Upload in progress: ${percent}%`,
+      errorAnnouncement: (message) => `Error: ${message}`,
+    },
+  };
+}

package/src/react/failures.ts

@@ -1,3 +1,5 @@
+import type { UploadButtonCopy } from '@12-apps/ui/copy';
+
 import { ACCEPTED_CONTENT_TYPES } from '../content-types';
 import { megabytes } from '../limits';
 
@@ -109,6 +111,15 @@ export interface WebStorageMessages {
   fieldLabel: string;
   fieldHelper: string;
   fieldRemove: string;
+  /**
+   * What the dropzone ITSELF says — its hint line, its accessible name, and
+   * the three announcements only a screen reader receives. `@12-apps/ui` stopped
+   * shipping English defaults for these, so a host that answers `fieldLabel`
+   * and nothing else would have a dropzone with no name and a silent progress
+   * bar. `buttonLabel` is unused here: `ImageField` passes `fieldLabel` as the
+   * override, because the field's own label is the one a form already names.
+   */
+  field: UploadButtonCopy;
 }
 
 /** Copy that only makes sense with the configured ceiling in it. */

package/src/react/image-field.tsx

@@ -5,6 +5,7 @@ import { Box } from '@12-apps/ui/mui/Box';
 import { Stack } from '@12-apps/ui/mui/Stack';
 import { Text } from '@12-apps/ui/typography/Text';
 import { Button } from '@12-apps/ui/form/Button';
+import type { UploadButtonCopy } from '@12-apps/ui/copy';
 import { UploadButton } from '@12-apps/ui/form/UploadButton';
 
 import { ACCEPTED_CONTENT_TYPES } from '../content-types';
@@ -38,6 +39,13 @@ export interface ImageFieldProps {
   label: string;
   /** The button that clears a chosen image. REQUIRED, for the same reason. */
   removeLabel: string;
+  /**
+   * What the dropzone itself says — the hint under the label, its accessible
+   * name, and the three announcements only a screen reader receives. REQUIRED:
+   * `@12-apps/ui` ships no default copy, so without this the dropzone has no
+   * name and a silent progress bar.
+   */
+  uploadCopy: UploadButtonCopy;
   helperText?: string;
   /** Passed through per upload — `{ optimize: false }` for a rendered canvas. */
   uploadOptions?: UploadOptions;
@@ -92,6 +100,9 @@ export function ImageField(props: BoundImageFieldProps): JSX.Element {
       ) : null}
       <UploadButton
         variant="dropzone"
+        copy={props.uploadCopy}
+        // The field's own label wins over `uploadCopy.buttonLabel`: a form
+        // already names this field, and naming it twice is how the two drift.
         label={props.label}
         accept={ACCEPT}
         disabled={props.disabled || uploader.uploading}

package/src/react/index.ts

@@ -42,3 +42,5 @@ export {
   type WebStorageMessages,
 } from './failures';
 export { PT_BR_WEB_STORAGE_MESSAGES } from './pt-BR';
+export { EN_US_WEB_STORAGE_MESSAGES } from './en-US';
+export { WEB_STORAGE_MESSAGES } from './locales';

package/src/react/locales.ts

@@ -0,0 +1,18 @@
+import { EN_US_WEB_STORAGE_MESSAGES } from './en-US';
+import type { WebStorageMessageContext, WebStorageMessages } from './failures';
+import { PT_BR_WEB_STORAGE_MESSAGES } from './pt-BR';
+
+/**
+ * Both languages of the browser half, keyed by tag. Factories, for the reason
+ * the server pack's docstring gives: the ceiling is interpolated so copy cannot
+ * name a limit the host has since changed.
+ *
+ * `LocalePack` is mirrored here rather than imported so the package stays
+ * liftable into a repo that has never heard of `@12-apps/i18n`.
+ */
+type LocalePack<T> = { readonly 'pt-BR': T; readonly 'en-US': T };
+
+export const WEB_STORAGE_MESSAGES = {
+  'pt-BR': PT_BR_WEB_STORAGE_MESSAGES,
+  'en-US': EN_US_WEB_STORAGE_MESSAGES,
+} as const satisfies LocalePack<(context: WebStorageMessageContext) => WebStorageMessages>;

package/src/react/pt-BR.ts

@@ -35,5 +35,18 @@ export function PT_BR_WEB_STORAGE_MESSAGES(
     fieldLabel: 'Foto do produto',
     fieldHelper: 'A imagem é reduzida no navegador antes do envio.',
     fieldRemove: 'Remover imagem',
+    field: {
+      // `buttonLabel` is never read here — `ImageField` overrides it with
+      // `fieldLabel`. It is still answered, because the type is the whole of
+      // what `UploadButton` may render and a partial answer is not a pack.
+      buttonLabel: 'Foto do produto',
+      dropzoneHint: 'Solte a imagem aqui ou clique para escolher',
+      dropzoneRole: (label) => `Área de upload de imagem. ${label}`,
+      uploading: 'Enviando…',
+      dropReady: 'Imagem pronta para soltar',
+      percentUploaded: (percent) => `${percent}% enviado`,
+      uploadInProgress: (percent) => `Envio em andamento: ${percent}%`,
+      errorAnnouncement: (message) => `Erro: ${message}`,
+    },
   };
 }