@molecule/app-image-gallery-editor-react 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,146 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-04T01:51:06.106Z
+-->
+
+# @molecule/app-image-gallery-editor-react
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+`@molecule/app-image-gallery-editor-react` — hero drop zone + side grid of
+thumbnail slots. Click an empty slot or the drop zone to upload; click a
+filled slot to remove (native `window.confirm`).
+
+Stateless about persistence — the consumer owns the slot array and handles
+uploads via `onPickFiles` (defaults to local object URLs for preview).
+
+## Quick Start
+
+```tsx
+import { useState } from 'react'
+import { ImageGalleryEditor } from '@molecule/app-image-gallery-editor-react'
+
+function GalleryEditor() {
+  const [slots, setSlots] = useState<(string | null)[]>(Array(4).fill(null))
+  return (
+    <ImageGalleryEditor
+      slots={slots}
+      onChange={setSlots}
+      onPickFiles={async (files) => {
+        // upload each file, return persisted URLs (null keeps a slot empty)
+        return Array.from(files).map((f) => URL.createObjectURL(f))
+      }}
+      header={<h3>Image Gallery</h3>}
+      counter={`${slots.filter(Boolean).length} / 24 Photos`}
+    />
+  )
+}
+```
+
+## Type
+
+`feature`
+
+## Installation
+
+```bash
+npm install @molecule/app-image-gallery-editor-react @molecule/app-icons @molecule/app-react @molecule/app-ui @molecule/app-ui-react react
+npm install -D @types/react
+```
+
+## API
+
+### Interfaces
+
+#### `ImageGalleryEditorProps`
+
+Props for {@link ImageGalleryEditor}.
+
+```typescript
+interface ImageGalleryEditorProps {
+  /** Ordered slots, `null` for empty. Length determines slot count. */
+  slots: (string | null)[]
+  onChange: (slots: (string | null)[]) => void
+  /** Called when the user picks files; defaults to a local object URL. */
+  onPickFiles?: (files: FileList) => Promise<(string | null)[]> | (string | null)[]
+  maxImages?: number
+  /** Header heading + subtitle slot (renders left of the photo counter). */
+  header?: ReactNode
+  /** Photo-counter label (e.g. "3 / 24 Photos"). */
+  counter?: ReactNode
+  dropZoneTitle?: ReactNode
+  dropZoneHint?: ReactNode
+  confirmRemoveMessage?: string
+  statusMessage?: ReactNode
+  /**
+   * Glyph rendered in empty slots — a typed `IconName` from the bonded
+   * `@molecule/app-icons` set (an unknown name is a type error, not a blank).
+   */
+  emptySlotIcon?: IconName
+}
+```
+
+### Functions
+
+#### `ImageGalleryEditor(props)`
+
+Editable image gallery primitive.
+
+```typescript
+function ImageGalleryEditor({
+  slots,
+  onChange,
+  onPickFiles,
+  maxImages = 24,
+  header,
+  counter,
+  dropZoneTitle = 'Drag and drop assets here',
+  dropZoneHint = 'or click to browse local files',
+  confirmRemoveMessage = 'Remove this image?',
+  statusMessage,
+  emptySlotIcon = 'image',
+}: ImageGalleryEditorProps): JSX.Element
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-icons` ^1.0.1
+- `@molecule/app-react` ^1.0.1
+- `@molecule/app-ui` ^1.0.1
+- `@molecule/app-ui-react` ^1.0.1
+- `react` ^18.0.0 || ^19.0.0
+
+### Runtime Dependencies
+
+- `@molecule/app-icons`
+- `@molecule/app-react`
+- `@molecule/app-ui`
+- `@molecule/app-ui-react`
+- `react`
+
+- Styling is 100% ClassMap (`getClassMap()` / `cm.*`) — the editor renders
+  correctly out of the box under any bonded styling library and needs NO
+  per-app Tailwind `@source` scan of this package. (It previously hardcoded
+  raw Tailwind + Material-3 utility classes that no scaffold `@source`-scans,
+  so even the `hidden` file input never generated a rule and rendered
+  visible; the file input is now hidden with an inline `display:none`.) The
+  few `style={...}` values (grid-column span, aspect ratio, corner radius,
+  the dashed drop-zone border, `object-fit`, dim opacity, `display:none`)
+  are the documented ClassMap-can't-express cases and use real theme tokens.
+- Icons are real SVG glyphs from `@molecule/app-ui-react`'s `<Icon>`
+  (`upload`, `trash`, and the `emptySlotIcon` — a typed `IconName`) — NO
+  Material Symbols font to load. Requires a bonded `@molecule/app-icons` set.
+- The filled-slot delete affordance is always visible (touch-friendly)
+  rather than hover-revealed.
+- `dropZoneTitle` / `dropZoneHint` / `confirmRemoveMessage` default to
+  English strings — pass translated values (`t('...')`) in localized apps.
+- `getClassMap()` requires a bonded ClassMap for the layout primitives.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-image-gallery-editor-react",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Editable image gallery: hero drop zone + grid of thumbnail slots with click-to-remove and progress label. Extracted from property-listing ListingEditorImageGallery.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -27,18 +28,23 @@
     "react"
   ],
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/app/features/image-gallery-editor-react"
+  },
   "peerDependencies": {
-    "@molecule/app-icons": "^1.0.0",
-    "@molecule/app-react": "^1.0.0",
-    "@molecule/app-ui": "^1.0.0",
-    "@molecule/app-ui-react": "^1.0.0",
+    "@molecule/app-icons": "^1.0.1",
+    "@molecule/app-react": "^1.0.1",
+    "@molecule/app-ui": "^1.0.1",
+    "@molecule/app-ui-react": "^1.0.1",
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@molecule/app-icons": "1.0.0",
-    "@molecule/app-react": "1.0.0",
-    "@molecule/app-ui": "1.0.0",
-    "@molecule/app-ui-react": "1.0.0",
+    "@molecule/app-icons": "1.0.1",
+    "@molecule/app-react": "1.0.1",
+    "@molecule/app-ui": "1.0.1",
+    "@molecule/app-ui-react": "1.0.1",
     "@types/node": "26.1.2",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",