@scaleflex/light-dam

A lightweight, embeddable DAM web component for Scaleflex — built for Portals, Spotlight, and Cloudimage, where the full js-admin-react-filerobot-v5 admin is too heavy. light-dam covers browse + manage (folder/asset CRUD) + upload and deliberately leaves out the heavy DAM features (metadata, airboxes, shareboxes, approvals).

It's a Lit web component, matching the house format of @scaleflex/asset-picker and @scaleflex/uploader, so it drops into React, Vue, Angular, Svelte, or plain HTML.

📘 Full integration guide: INTEGRATION.md — install, auth, per-framework setup, events, theming, troubleshooting. ▶️ Try it: run the dev harness with pnpm --filter @scaleflex/light-dam dev (from the monorepo root) — paste a container + key (or set VITE_FR_*) and click through it.

Part of the scaleflex-dam-tools monorepo (apps/light-dam/). light-dam is built on the shared @scaleflex/dam-core package — see below.

Built on @scaleflex/dam-core

The framework-agnostic Filerobot auth / API / types / store / helpers layer that powers light-dam lives in the shared @scaleflex/dam-core package (packages/core/ in this monorepo), which light-dam, and progressively the other widgets, depend on — unifying a layer that used to be duplicated and divergent across the plugins. (It started life as a local src/core/ folder inside light-dam and has since been extracted into its own package.) light-dam imports the headless surface from @scaleflex/dam-core and re-exports it on its own . and ./core entry points, so consumers get it from one import path.

Distribution

| Import | Use | | ----------------------------- | ----------------------------------------------------------- | | @scaleflex/light-dam | Element class + types + dam-core surface (no auto-register) | | @scaleflex/light-dam/define | Registers <sfx-light-dam> (vanilla / any framework) | | @scaleflex/light-dam/react | <LightDam> React wrapper (Portals, Spotlight) | | @scaleflex/light-dam/core | Re-exports @scaleflex/dam-core (headless), standalone |

Web component

<sfx-light-dam id="dam"></sfx-light-dam>
<script type="module">
  import '@scaleflex/light-dam/define';
  document.getElementById('dam').config = {
    auth: { mode: 'sass-key', container: 'my-container', sassKey: '…' },
    rootFolder: '/',
  };
</script>

React

import { LightDam } from '@scaleflex/light-dam/react';

<LightDam
  config={{
    auth: { mode: 'security-template', container: 'my-container', securityTemplateId: '…' },
  }}
  onAssetSelect={(asset) => console.log(asset)}
  onFolderOpen={(path) => console.log(path)}
/>;

Configuration

config (set as a property on the element, or the config prop in React):

| Field | Type | Notes | | ------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | auth | { mode: 'sass-key', container, sassKey } or { mode: 'security-template', container, securityTemplateId } | Required. airboxPuid optional. | | apiDomain | string | Override the default https://api.filerobot.com host. | | rootFolder | string | Folder to open on load (default /). | | features | LightDamFeatures | Toggle upload, createFolder, rename, delete, move, favourites (all default true). | | favourites | FavouritesAdapter | Per-user persistence. Defaults to localStorage; hosts inject their own. |

Events

The element dispatches bubbling, composed CustomEvents (the React wrapper maps these to on* props):

| Event | detail | React prop | | -------------- | ----------- | --------------- | | asset-select | { asset } | onAssetSelect | | folder-open | { path } | onFolderOpen |

Theming

Re-skin without forking via CSS custom properties on the host — e.g. --sfx-ld-accent, --sfx-ld-fg, --sfx-ld-muted, --sfx-ld-border, --sfx-ld-bg, --sfx-ld-radius.

Architecture

apps/light-dam/src/
├── ui/          ← own Lit UI (shell + BrowseStoreController + views/); integrates @scaleflex/uploader
├── index.ts     ← "."        element + types + re-exported @scaleflex/dam-core
├── core.ts      ← "./core"   export * from '@scaleflex/dam-core'
├── define.ts    ← "./define" customElements.define
└── react.ts     ← "./react"  <LightDam> wrapper

packages/core/   ← @scaleflex/dam-core (UI-free: auth · api · store · types · helpers)

Approach — build clean, reuse the shared core: light-dam builds its own browse/manage UI; it does not depend on @scaleflex/asset-picker. The reusable, framework-agnostic logic (browse/list, navigation & selection state, CRUD, auth/API) lives in the shared @scaleflex/dam-core package, which light-dam consumes. asset-picker's source was referenced to port proven logic from (into dam-core), not imported.

Upload is the deliberate exception: light-dam integrates @scaleflex/uploader as-is (optional peer dep) — the canonical upload widget, also used in js-admin-react-filerobot-v5. It's composed, not rebuilt: a picker isn't a manager (extract), but the uploader is the uploader (compose).

Views

There is one content view — Assets — and three navigation scope axes into it (not separate screens):

| Sidebar axis | What it does | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Folders | Hierarchical tree + breadcrumb — the primary navigation spine | | Labels | Flat, cross-folder — pick a label to see all matching assets (labels are simple tags, not metadata) | | Favourites | Per-user starred assets via a pluggable FavouritesAdapter (default localStorage; hosts can inject one backed by Filerobot's native /users/favorites API or their own store) |

The Assets content renders in two display views you toggle between:

• Grid — thumbnail cards, with an S / M / L size control (default)
• List — sortable table (name · type · size · modified) for management & bulk select

Plus: a breadcrumb path bar, an asset preview panel (preview + basic info + rename / delete / move / download / copy CDN URL — no metadata editing), flat search results, an upload overlay (@scaleflex/uploader), and single + multi-select for bulk actions.

Deliberately out (stays in filerobot-v5): metadata editing, airboxes, shareboxes, approvals, Collections, and masonry/map/calendar views.

Develop

Run from the monorepo root (pnpm install once installs every workspace):

pnpm install                                   # at the monorepo root
pnpm --filter @scaleflex/light-dam dev         # polished demo SPA (serves demo/, default :5173)
pnpm --filter @scaleflex/light-dam demo        # per-framework examples (serves examples/)
pnpm --filter @scaleflex/light-dam typecheck   # tsc --noEmit
pnpm --filter @scaleflex/light-dam test        # vitest — jsdom UI render tests (core tests live in dam-core)
pnpm --filter @scaleflex/light-dam build       # vite lib build → dist/ (es + cjs + d.ts)

For live data, open the Auth panel in the demo and paste a container + SASS key (no restart needed). The examples harness also reads VITE_FR_CONTAINER / VITE_FR_SASS_KEY (e.g. in apps/light-dam/.env.local). Editing packages/core/src/... is reflected live with no rebuild.

Status: pre-release (0.1.0) — typecheck + build + tests green. Browse (Folders · Labels · Favourites with a lazy folder tree), Grid + List views, preview panel, folder/asset CRUD with in-shell modals + a folder-picker move, multi-select, and @scaleflex/uploader integration are all wired off @scaleflex/dam-core. Mutation endpoints are verified against filerobot-v5 and lists surface truncation honestly. Before production: run the dev harness with real credentials for a live end-to-end pass. Releases go through the monorepo's Changesets flow. See CLAUDE.md for the remaining punch list.