@workbench-kit/react 0.0.2-prototype.0.2.10 → 0.0.2-prototype.0.2.13

package/src/primitives/library-detail-layout/LibraryDetailLayout.tsx

@@ -1,23 +1,31 @@
 import './library-detail-layout.css';
-import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { useEffect, useState, type ComponentPropsWithRef, type ReactNode } from 'react';
 
 import { cx } from '../../utils/cx';
 import { WorkbenchMediaSlot } from '../workbench-media-slot';
 import { RecordMediaHero } from '../record-media-hero';
 import { ScrollArea } from '../scroll-area';
+import { resolveLibraryDetailHeroCoverMedia } from './resolve-hero-cover-media.js';
 
-export type LibraryDetailLayoutMode = 'background' | 'banner' | 'compact';
+export type LibraryDetailLayoutMode = 'background' | 'banner' | 'compact' | 'hero-cover';
 
 export interface LibraryDetailLayoutProps extends Omit<
   ComponentPropsWithRef<'div'>,
   'children' | 'title'
 > {
   readonly actions?: ReactNode;
+  /** Optional attribution / footer below the identity row (`hero-cover` mode). */
+  readonly attribution?: ReactNode;
   readonly backgroundImageUrl?: string | null;
   readonly children?: ReactNode;
   readonly coverAlt?: string;
   readonly coverImageUrl?: string | null;
   readonly description?: ReactNode;
+  /**
+   * Wide hero band URL for `hero-cover` mode. When omitted or identical to
+   * `coverImageUrl`, the cover is used as soft atmosphere behind the portrait.
+   */
+  readonly heroImageUrl?: string | null;
   readonly logoImageUrl?: string | null;
   readonly mode?: LibraryDetailLayoutMode;
   readonly summary?: ReactNode;
@@ -27,12 +35,14 @@ export interface LibraryDetailLayoutProps extends Omit<
 
 export function LibraryDetailLayout({
   actions,
+  attribution,
   backgroundImageUrl = null,
   children,
   className,
   coverAlt,
   coverImageUrl = null,
   description,
+  heroImageUrl = null,
   logoImageUrl = null,
   mode = 'banner',
   summary,
@@ -41,7 +51,13 @@ export function LibraryDetailLayout({
   ...props
 }: LibraryDetailLayoutProps): ReactNode {
   const resolvedMode =
-    mode === 'background' ? 'background' : mode === 'compact' ? 'compact' : 'banner';
+    mode === 'background'
+      ? 'background'
+      : mode === 'compact'
+        ? 'compact'
+        : mode === 'hero-cover'
+          ? 'hero-cover'
+          : 'banner';
 
   return (
     <div
@@ -54,7 +70,18 @@ export function LibraryDetailLayout({
       {...props}
     >
       {toolbar}
-      {resolvedMode === 'background' ? (
+      {resolvedMode === 'hero-cover' ? (
+        <LibraryDetailHeroCover
+          actions={actions}
+          attribution={attribution}
+          coverAlt={coverAlt}
+          coverImageUrl={coverImageUrl}
+          description={description}
+          heroImageUrl={heroImageUrl ?? backgroundImageUrl}
+          summary={summary}
+          title={title}
+        />
+      ) : resolvedMode === 'background' ? (
         <div className="ui-library-detail-layout__band" data-ui-library-detail-band="true">
           <RecordMediaHero
             alt={coverAlt}
@@ -105,6 +132,93 @@ export function LibraryDetailLayout({
   );
 }
 
+function LibraryDetailHeroCover({
+  actions,
+  attribution,
+  coverAlt,
+  coverImageUrl,
+  description,
+  heroImageUrl,
+  summary,
+  title,
+}: {
+  actions?: ReactNode;
+  attribution?: ReactNode;
+  coverAlt?: string;
+  coverImageUrl: string | null;
+  description?: ReactNode;
+  heroImageUrl: string | null;
+  summary?: ReactNode;
+  title: ReactNode;
+}): ReactNode {
+  const [heroFailed, setHeroFailed] = useState(false);
+  const [coverFailed, setCoverFailed] = useState(false);
+
+  useEffect(() => {
+    setHeroFailed(false);
+  }, [heroImageUrl]);
+
+  useEffect(() => {
+    setCoverFailed(false);
+  }, [coverImageUrl]);
+
+  const media = resolveLibraryDetailHeroCoverMedia({
+    heroImageUrl,
+    coverImageUrl,
+    heroFailed,
+    coverFailed,
+  });
+
+  return (
+    <div className="ui-library-detail-layout__hero-cover" data-ui-library-detail-hero-cover="true">
+      <div className="ui-library-detail-layout__band" data-ui-library-detail-band="true">
+        <RecordMediaHero
+          alt={coverAlt}
+          className={cx(
+            'ui-library-detail-layout__band-media',
+            media.bandKind === 'atmosphere' && 'ui-library-detail-layout__band-media--atmosphere',
+          )}
+          data-atmosphere={media.bandKind === 'atmosphere' ? 'true' : undefined}
+          fallbackIcon="library"
+          imageUrl={media.bandImageUrl}
+          layout="background"
+          onImageError={() => {
+            if (media.bandKind === 'hero') {
+              setHeroFailed(true);
+            } else if (media.bandKind === 'atmosphere') {
+              setCoverFailed(true);
+            }
+          }}
+        />
+        <div aria-hidden className="ui-library-detail-layout__band-overlay" />
+      </div>
+      <div className="ui-library-detail-layout__hero-cover-body">
+        {media.showPortraitCover ? (
+          <RecordMediaHero
+            alt={coverAlt}
+            className="ui-library-detail-layout__portrait-cover"
+            fallbackIcon="library"
+            imageUrl={media.resolvedCover}
+            layout="compact"
+            onImageError={() => setCoverFailed(true)}
+          />
+        ) : null}
+        <div className="ui-library-detail-layout__hero-content">
+          <div className="ui-library-detail-layout__title">{title}</div>
+          {summary ? <div className="ui-library-detail-layout__summary">{summary}</div> : null}
+          {actions ? <div className="ui-library-detail-layout__actions">{actions}</div> : null}
+          {description ? (
+            <div className="ui-library-detail-layout__description">{description}</div>
+          ) : null}
+          {attribution ? (
+            <div className="ui-library-detail-layout__attribution">{attribution}</div>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}
+
 function LibraryDetailIdentity({
   logoImageUrl,
   summary,

package/src/primitives/library-detail-layout/index.ts

@@ -1 +1,6 @@
 export * from './LibraryDetailLayout';
+export {
+  resolveLibraryDetailHeroCoverMedia,
+  type ResolveLibraryDetailHeroCoverMediaInput,
+  type ResolvedLibraryDetailHeroCoverMedia,
+} from './resolve-hero-cover-media.js';

package/src/primitives/library-detail-layout/library-detail-layout.css

@@ -4,6 +4,11 @@
   --shell-library-capsule-list-height: 43px;
   --shell-detail-hero-cover-width: 231px;
   --shell-detail-hero-cover-height: calc(var(--shell-detail-hero-cover-width, 231px) * 43 / 116);
+  --shell-detail-portrait-cover-width: 120px;
+  --shell-detail-portrait-cover-height: 160px;
+  --shell-detail-atmosphere-blur: 18px;
+  --shell-detail-atmosphere-scale: 1.12;
+  --shell-detail-atmosphere-opacity: 0.55;
   --shell-library-detail-logo-size: 56px;
   --shell-library-detail-thumb-width: var(--shell-library-capsule-list-width, 116px);
   --shell-library-detail-thumb-height: var(--shell-library-capsule-list-height, 43px);
@@ -167,3 +172,55 @@
   aspect-ratio: var(--shell-library-capsule-aspect, 116 / 43);
   flex: 0 0 auto;
 }
+
+.ui-library-detail-layout__hero-cover {
+  display: grid;
+  gap: 0;
+  min-width: 0;
+}
+
+.ui-library-detail-layout__hero-cover .ui-library-detail-layout__band {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+.ui-library-detail-layout__band-media--atmosphere .ui-record-media-hero__image,
+.ui-library-detail-layout__band-media[data-atmosphere='true'] .ui-record-media-hero__image {
+  opacity: var(--shell-detail-atmosphere-opacity, 0.55);
+  filter: blur(var(--shell-detail-atmosphere-blur, 18px));
+  transform: scale(var(--shell-detail-atmosphere-scale, 1.12));
+  object-fit: cover;
+}
+
+.ui-library-detail-layout__hero-cover-body {
+  display: flex;
+  gap: 16px;
+  align-items: flex-end;
+  margin-top: -48px;
+  padding: 0 16px 8px;
+  position: relative;
+  z-index: 2;
+}
+
+.ui-library-detail-layout__portrait-cover.ui-record-media-hero--compact {
+  box-sizing: border-box;
+  width: var(--shell-detail-portrait-cover-width, 120px);
+  min-width: var(--shell-detail-portrait-cover-width, 120px);
+  max-width: var(--shell-detail-portrait-cover-width, 120px);
+  height: var(--shell-detail-portrait-cover-height, 160px);
+  min-height: var(--shell-detail-portrait-cover-height, 160px);
+  max-height: var(--shell-detail-portrait-cover-height, 160px);
+  aspect-ratio: auto;
+  flex: 0 0 auto;
+  border: 1px solid
+    var(--shell-color-border-subtle, var(--color-border-subtle, rgba(255, 255, 255, 0.12)));
+  border-radius: var(--shell-radius-sm, 4px);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.28);
+  overflow: hidden;
+}
+
+.ui-library-detail-layout__attribution {
+  color: var(--shell-color-text-subtle, var(--color-text-subtle, var(--color-text-muted)));
+  font-size: var(--shell-font-size-caption, 0.75rem);
+  line-height: 1.4;
+}

package/src/primitives/library-detail-layout/resolve-hero-cover-media.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure media resolution for LibraryDetailLayout `hero-cover` mode.
+ * Implements atmosphere-from-cover when no distinct wide hero URL succeeds.
+ */
+
+export interface ResolveLibraryDetailHeroCoverMediaInput {
+  readonly heroImageUrl?: string | null;
+  readonly coverImageUrl?: string | null;
+  readonly heroFailed?: boolean;
+  readonly coverFailed?: boolean;
+}
+
+export interface ResolvedLibraryDetailHeroCoverMedia {
+  /** Trimmed cover URL when load has not failed. */
+  readonly resolvedCover: string | null;
+  /** Distinct wide hero URL (differs from cover) when load has not failed. */
+  readonly resolvedHero: string | null;
+  /**
+   * Soft backdrop URL when there is no successful distinct hero but cover is
+   * available. Must not be stretched as the sole full-bleed identity cover.
+   */
+  readonly atmosphereUrl: string | null;
+  /** Band media to render: distinct hero, else atmosphere, else null (fallback). */
+  readonly bandImageUrl: string | null;
+  readonly bandKind: 'hero' | 'atmosphere' | 'fallback';
+  readonly showPortraitCover: boolean;
+}
+
+function trimUrl(value: string | null | undefined): string | null {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed === '' ? null : trimmed;
+}
+
+export function resolveLibraryDetailHeroCoverMedia(
+  input: ResolveLibraryDetailHeroCoverMediaInput,
+): ResolvedLibraryDetailHeroCoverMedia {
+  const coverSource = trimUrl(input.coverImageUrl);
+  const heroSource = trimUrl(input.heroImageUrl);
+  const heroFailed = input.heroFailed ?? false;
+  const coverFailed = input.coverFailed ?? false;
+
+  const resolvedCover = coverSource && !coverFailed ? coverSource : null;
+  const distinctHero = heroSource && coverSource && heroSource === coverSource ? null : heroSource;
+  const resolvedHero = distinctHero && !heroFailed ? distinctHero : null;
+  const atmosphereUrl = !resolvedHero && resolvedCover ? resolvedCover : null;
+
+  if (resolvedHero) {
+    return {
+      resolvedCover,
+      resolvedHero,
+      atmosphereUrl: null,
+      bandImageUrl: resolvedHero,
+      bandKind: 'hero',
+      showPortraitCover: resolvedCover !== null,
+    };
+  }
+
+  if (atmosphereUrl) {
+    return {
+      resolvedCover,
+      resolvedHero: null,
+      atmosphereUrl,
+      bandImageUrl: atmosphereUrl,
+      bandKind: 'atmosphere',
+      showPortraitCover: true,
+    };
+  }
+
+  return {
+    resolvedCover,
+    resolvedHero: null,
+    atmosphereUrl: null,
+    bandImageUrl: null,
+    bandKind: 'fallback',
+    showPortraitCover: false,
+  };
+}

package/src/primitives/record-media-hero/RecordMediaHero.tsx

@@ -15,6 +15,8 @@ export interface RecordMediaHeroProps extends ComponentPropsWithRef<'div'> {
   layout?: RecordMediaHeroLayout;
   logoUrl?: string | null;
   maxWidth?: number | string;
+  /** Forwarded when the primary hero/cover image fails to load. */
+  onImageError?: () => void;
 }
 
 function resolveMaxWidth(maxWidth: number | string | undefined): CSSProperties['maxWidth'] {
@@ -33,6 +35,7 @@ export function RecordMediaHero({
   layout = 'banner',
   logoUrl = null,
   maxWidth,
+  onImageError,
   style,
   ...props
 }: RecordMediaHeroProps) {
@@ -66,6 +69,7 @@ export function RecordMediaHero({
         imageClassName="ui-record-media-hero__image"
         imageUrl={imageUrl}
         loading="eager"
+        onImageError={onImageError}
       />
       {logoMedia.shouldShowImage ? (
         <img

package/src/primitives/workbench-media-slot/WorkbenchMediaSlot.tsx

@@ -20,6 +20,8 @@ export interface WorkbenchMediaSlotProps extends Omit<ComponentPropsWithRef<'spa
    * Pass `eager` for above-the-fold heroes and detail identity art.
    */
   loading?: 'eager' | 'lazy';
+  /** Optional host callback after the slot marks the current URL as failed. */
+  onImageError?: () => void;
 }
 
 export function WorkbenchMediaSlot({
@@ -33,6 +35,7 @@ export function WorkbenchMediaSlot({
   imageClassName,
   imageUrl = null,
   loading = 'lazy',
+  onImageError,
   ...props
 }: WorkbenchMediaSlotProps) {
   const media = useWorkbenchMediaImage(imageUrl);
@@ -47,7 +50,10 @@ export function WorkbenchMediaSlot({
           alt={alt ?? ''}
           className={cx('ui-workbench-media-slot__image', imageClassName)}
           loading={loading}
-          onError={media.onImageError}
+          onError={() => {
+            media.onImageError();
+            onImageError?.();
+          }}
           src={media.imageSrc}
         />
       ) : (

package/src/workbench/management/createWorkbenchNotify.tsx

@@ -0,0 +1,88 @@
+import type { ReactNode } from 'react';
+
+import type {
+  ShowWorkbenchNoticeInput,
+  WorkbenchNoticeController,
+  WorkbenchNoticeTone,
+} from './WorkbenchNotice.js';
+
+export interface WorkbenchNotificationAction {
+  readonly label: string;
+  readonly onAction: () => void;
+}
+
+export interface WorkbenchNotifyOptions {
+  readonly actions?: readonly WorkbenchNotificationAction[];
+  readonly dataAttributes?: ShowWorkbenchNoticeInput['dataAttributes'];
+  readonly durationMs?: number;
+  readonly id?: string;
+}
+
+/**
+ * NotificationService-shaped facade over {@link WorkbenchNoticeController}.
+ * Prefer this for command/install/save feedback; keep modal confirms separate.
+ */
+export interface WorkbenchNotify {
+  info(message: ReactNode, options?: WorkbenchNotifyOptions): string;
+  error(message: ReactNode, options?: WorkbenchNotifyOptions): string;
+  success(message: ReactNode, options?: WorkbenchNotifyOptions): string;
+  warning(message: ReactNode, options?: WorkbenchNotifyOptions): string;
+  dismiss(id: string): void;
+  clear(): void;
+}
+
+function showTone(
+  controller: WorkbenchNoticeController,
+  tone: WorkbenchNoticeTone,
+  message: ReactNode,
+  options: WorkbenchNotifyOptions = {},
+): string {
+  const { actions, dataAttributes, durationMs, id } = options;
+  const noticeId = id ?? `workbench-notify-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  const noticeMessage =
+    actions && actions.length > 0 ? (
+      <span className="ui-workbench-notify-message">
+        <span className="ui-workbench-notify-message__text">{message}</span>
+        <span className="ui-workbench-notify-message__actions">
+          {actions.map((action) => (
+            <button
+              className="ui-workbench-notify-message__action"
+              key={action.label}
+              type="button"
+              onClick={() => {
+                action.onAction();
+                controller.dismissNotice(noticeId);
+              }}
+            >
+              {action.label}
+            </button>
+          ))}
+        </span>
+      </span>
+    ) : (
+      message
+    );
+
+  return controller.showNotice({
+    ...(dataAttributes === undefined ? {} : { dataAttributes }),
+    ...(durationMs === undefined ? {} : { durationMs }),
+    id: noticeId,
+    message: noticeMessage,
+    tone,
+  });
+}
+
+/**
+ * Create a `notify.info` / `notify.error` facade over an existing notice controller.
+ */
+export function createWorkbenchNotify(controller: WorkbenchNoticeController): WorkbenchNotify {
+  return {
+    info: (message, options) => showTone(controller, 'info', message, options),
+    error: (message, options) => showTone(controller, 'error', message, options),
+    success: (message, options) => showTone(controller, 'success', message, options),
+    warning: (message, options) => showTone(controller, 'warning', message, options),
+    dismiss: (noticeId) => controller.dismissNotice(noticeId),
+    clear: () => controller.clearNotices(),
+  };
+}

package/src/workbench/management/index.ts

@@ -75,6 +75,13 @@ export type {
   WorkbenchNoticePosition,
   WorkbenchNoticeTone,
 } from './WorkbenchNotice.js';
+export { createWorkbenchNotify } from './createWorkbenchNotify.js';
+export type {
+  WorkbenchNotificationAction,
+  WorkbenchNotify,
+  WorkbenchNotifyOptions,
+} from './createWorkbenchNotify.js';
+export { useWorkbenchNotify } from './useWorkbenchNotify.js';
 export { KeybindingCaptureField } from './KeybindingCaptureField.js';
 export type { KeybindingCaptureFieldProps } from './KeybindingCaptureField.js';
 export { KeybindingManagementPanel } from './KeybindingManagementPanel.js';

package/src/workbench/management/management.css

@@ -2,3 +2,31 @@
 @import './library-catalog-picker-dialog.css';
 @import './library-facet-filter-dialog.css';
 @import './management-panel.css';
+
+.ui-workbench-notify-message {
+  display: inline-flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-items: center;
+}
+
+.ui-workbench-notify-message__actions {
+  display: inline-flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.ui-workbench-notify-message__action {
+  margin: 0;
+  padding: 2px 8px;
+  border: 1px solid var(--color-border, currentColor);
+  border-radius: var(--radius-sm, 4px);
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.ui-workbench-notify-message__action:hover {
+  background: var(--color-surface-hover, rgba(255, 255, 255, 0.08));
+}

package/src/workbench/management/useWorkbenchNotify.ts

@@ -0,0 +1,10 @@
+import { useMemo } from 'react';
+
+import { createWorkbenchNotify, type WorkbenchNotify } from './createWorkbenchNotify.js';
+import { useWorkbenchNotice } from './WorkbenchNotice.js';
+
+/** Convenience hook: NotificationService-shaped API inside a notice provider. */
+export function useWorkbenchNotify(): WorkbenchNotify {
+  const controller = useWorkbenchNotice();
+  return useMemo(() => createWorkbenchNotify(controller), [controller]);
+}

package/src/workbench/theme/themePresets.ts

@@ -20,6 +20,7 @@ export const DARK_THEME_PRESET_MANIFEST = [
   { id: 'modern', label: 'Modern Dark' },
   { id: 'dark-plus', label: 'Dark+' },
   { id: 'hc-black', label: 'High Contrast Black' },
+  { id: 'slate', label: 'Slate (alias pack)' },
 ] as const satisfies readonly WorkbenchThemePresetManifestEntry[];
 
 export type LightThemePresetId = (typeof LIGHT_THEME_PRESET_MANIFEST)[number]['id'];