@workbench-kit/react 0.0.2-prototype.0.1.2 → 0.0.2-prototype.0.2.2

package/src/primitives/catalog-browse-pane/CatalogBrowsePane.tsx

@@ -0,0 +1,360 @@
+import './catalog-browse-pane.css';
+import {
+  Fragment,
+  useRef,
+  type ComponentPropsWithRef,
+  type MouseEvent as ReactMouseEvent,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+
+import { cx } from '../../utils/cx';
+import { ClearableTextInput } from '../clearable-text-input/ClearableTextInput';
+import { CatalogBrowseCard } from '../catalog-browse-card/CatalogBrowseCard';
+import { EmptyState } from '../empty-state/EmptyState';
+import { IconButton } from '../icon-button/IconButton';
+import { List, ListEmptyState, ListItem } from '../list/List';
+import { ScrollArea } from '../scroll-area/ScrollArea';
+import { ScrollAreaInfiniteSentinel } from '../scroll-area-infinite-load/ScrollAreaInfiniteSentinel';
+import { useScrollAreaInfiniteLoad } from '../scroll-area-infinite-load/useScrollAreaInfiniteLoad';
+import { Select } from '../select';
+import { WorkbenchThumbnail } from '../workbench-thumbnail/WorkbenchThumbnail';
+import { SegmentedControl } from '../workbench-editor/WorkbenchEditor';
+import { FilterBar, FilterBarRow } from '../../layout/panel';
+
+/**
+ * Catalog browse frame (search / sort / grid|list / infinite scroll).
+ * Product-neutral — hosts own domain labels and item render overrides.
+ */
+export type CatalogBrowseViewMode = 'grid' | 'list';
+
+/**
+ * Catalog row for the default grid/list renderers.
+ * Hosts with richer cards should pass `renderGridItem` / `renderListItem`.
+ */
+export interface CatalogBrowseItem {
+  readonly description?: string | null | undefined;
+  readonly id: string;
+  readonly imageAlt?: string | undefined;
+  readonly imageUrl?: string | null | undefined;
+  readonly label: string;
+  readonly meta?: string | null | undefined;
+}
+
+export interface CatalogBrowseItemRenderState {
+  readonly selected: boolean;
+}
+
+export interface CatalogBrowsePaneProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  readonly clearSearchLabel: string;
+  readonly emptyMessage: string;
+  readonly errorMessage?: string | null | undefined;
+  /** Slot between search and sort/view controls (facet trigger, chips, etc.). */
+  readonly facetStrip?: ReactNode;
+  readonly gridAriaLabel?: string | undefined;
+  /** Visual label for the grid view-mode segment (string or icon node). */
+  readonly gridLabel?: ReactNode;
+  readonly hasMore: boolean;
+  readonly isLoading: boolean;
+  readonly isLoadingMore: boolean;
+  readonly items: ReadonlyArray<CatalogBrowseItem>;
+  readonly listAriaLabel?: string | undefined;
+  /** Visual label for the list view-mode segment (string or icon node). */
+  readonly listLabel?: ReactNode;
+  readonly loadingMessage: string;
+  readonly onItemContextMenu?:
+    ((itemId: string, itemLabel: string, event: ReactMouseEvent<HTMLElement>) => void) | undefined;
+  readonly onLoadMore: () => void;
+  readonly onOpenItem: (itemId: string) => void;
+  readonly onRefresh?: (() => void) | null | undefined;
+  readonly onSearchQueryChange: (query: string) => void;
+  readonly onSortChange?: ((sort: string) => void) | undefined;
+  readonly onViewModeChange: (viewMode: CatalogBrowseViewMode) => void;
+  readonly refreshLabel?: string | null | undefined;
+  readonly renderGridItem?:
+    ((item: CatalogBrowseItem, state: CatalogBrowseItemRenderState) => ReactNode) | undefined;
+  readonly renderListItem?:
+    ((item: CatalogBrowseItem, state: CatalogBrowseItemRenderState) => ReactNode) | undefined;
+  readonly searchAriaLabel: string;
+  readonly searchPlaceholder: string;
+  readonly searchQuery: string;
+  readonly selectedItemId?: string | null | undefined;
+  readonly sort?: string | undefined;
+  readonly sortAriaLabel?: string | undefined;
+  readonly sortOptions?: ReadonlyArray<{ label: string; value: string }> | undefined;
+  /** Extra trailing controls after built-in sort / view mode (before refresh). */
+  readonly toolbarTrailing?: ReactNode;
+  readonly viewMode: CatalogBrowseViewMode;
+  readonly viewModeAriaLabel?: string | undefined;
+}
+
+export function CatalogBrowsePane({
+  className,
+  clearSearchLabel,
+  emptyMessage,
+  errorMessage = null,
+  facetStrip = null,
+  gridAriaLabel,
+  gridLabel = 'Grid',
+  hasMore,
+  isLoading,
+  isLoadingMore,
+  items,
+  listAriaLabel,
+  listLabel = 'List',
+  loadingMessage,
+  onItemContextMenu,
+  onLoadMore,
+  onOpenItem,
+  onRefresh = null,
+  onSearchQueryChange,
+  onSortChange,
+  onViewModeChange,
+  refreshLabel = 'Refresh',
+  renderGridItem,
+  renderListItem,
+  searchAriaLabel,
+  searchPlaceholder,
+  searchQuery,
+  selectedItemId = null,
+  sort,
+  sortAriaLabel = 'Sort',
+  sortOptions,
+  toolbarTrailing = null,
+  viewMode,
+  viewModeAriaLabel = 'Catalog view mode',
+  ...props
+}: CatalogBrowsePaneProps): ReactNode {
+  const scrollAreaRef = useRef<HTMLDivElement>(null);
+  const { sentinelRef } = useScrollAreaInfiniteLoad({
+    hasMore,
+    isLoading,
+    isLoadingMore,
+    onLoadMore,
+    scrollAreaRef,
+  });
+
+  const showInitialLoading = isLoading && items.length === 0;
+  const showEmptyResults = !isLoading && !errorMessage && items.length === 0;
+  const resolvedSortOptions = sortOptions ?? [];
+  const hasSort =
+    resolvedSortOptions.length > 0 && typeof onSortChange === 'function' && sort !== undefined;
+
+  return (
+    <div
+      className={cx('ui-workbench-column', 'ui-catalog-browse', className)}
+      data-ui-catalog-browse="true"
+      {...props}
+    >
+      <FilterBar>
+        <FilterBarRow
+          className="ui-catalog-browse__toolbar"
+          data-columns={facetStrip ? undefined : 'search-action'}
+          data-ui-catalog-browse-has-sort={hasSort ? 'true' : undefined}
+          data-ui-catalog-browse-toolbar="true"
+          data-ui-catalog-browse-toolbar-filter={facetStrip ? 'true' : undefined}
+        >
+          <div className="ui-catalog-browse__search" data-ui-catalog-browse-search="true">
+            <ClearableTextInput
+              aria-label={searchAriaLabel}
+              clearLabel={clearSearchLabel}
+              controlWidth="full"
+              onValueChange={onSearchQueryChange}
+              placeholder={searchPlaceholder}
+              value={searchQuery}
+            />
+          </div>
+          {facetStrip}
+          {hasSort ? (
+            <div className="ui-catalog-browse__sort" data-ui-catalog-browse-sort="true">
+              <Select
+                aria-label={sortAriaLabel}
+                controlWidth="full"
+                onValueChange={onSortChange}
+                value={sort}
+              >
+                {resolvedSortOptions.map((option) => (
+                  <option key={option.value} value={option.value}>
+                    {option.label}
+                  </option>
+                ))}
+              </Select>
+            </div>
+          ) : null}
+          <SegmentedControl
+            ariaLabel={viewModeAriaLabel}
+            compact
+            onChange={onViewModeChange}
+            options={[
+              {
+                ariaLabel: typeof gridLabel === 'string' ? undefined : (gridAriaLabel ?? 'Grid'),
+                label: gridLabel,
+                value: 'grid',
+              },
+              {
+                ariaLabel: typeof listLabel === 'string' ? undefined : (listAriaLabel ?? 'List'),
+                label: listLabel,
+                value: 'list',
+              },
+            ]}
+            value={viewMode}
+          />
+          {toolbarTrailing}
+          {onRefresh ? (
+            <IconButton
+              data-ui-catalog-browse-refresh="true"
+              disabled={isLoading}
+              icon="codicon-refresh"
+              label={refreshLabel ?? 'Refresh'}
+              onClick={onRefresh}
+            />
+          ) : null}
+        </FilterBarRow>
+      </FilterBar>
+
+      {errorMessage ? (
+        <ListEmptyState data-ui-catalog-browse-error="true" tone="error">
+          {errorMessage}
+        </ListEmptyState>
+      ) : null}
+      {showInitialLoading ? (
+        <EmptyState compact data-ui-catalog-browse-loading="true" icon="loading">
+          {loadingMessage}
+        </EmptyState>
+      ) : null}
+      {showEmptyResults ? (
+        <EmptyState compact data-ui-catalog-browse-empty="true" icon="library">
+          {emptyMessage}
+        </EmptyState>
+      ) : null}
+
+      {items.length > 0 && viewMode === 'grid' ? (
+        <ScrollArea
+          aria-label={gridAriaLabel ?? (typeof gridLabel === 'string' ? gridLabel : 'Grid')}
+          className={cx('ui-workbench-panel-scroll', 'ui-catalog-browse__grid')}
+          data-ui-catalog-browse-grid="true"
+          gutter="auto"
+          orientation="vertical"
+          ref={scrollAreaRef}
+          role="list"
+        >
+          {items.map((item) => {
+            const selected = selectedItemId === item.id;
+            if (renderGridItem) {
+              return <Fragment key={item.id}>{renderGridItem(item, { selected })}</Fragment>;
+            }
+            return (
+              <CatalogBrowseCard
+                data-ui-catalog-browse-item={item.id}
+                imageAlt={item.imageAlt ?? item.label}
+                imageUrl={item.imageUrl ?? null}
+                key={item.id}
+                label={item.label}
+                meta={item.meta ?? undefined}
+                onClick={() => onOpenItem(item.id)}
+                onContextMenu={(event) => {
+                  onItemContextMenu?.(item.id, item.label, event);
+                }}
+                selected={selected}
+                tooltip={item.label}
+                variant="cover"
+              />
+            );
+          })}
+          <BrowseScrollFooter
+            hasMore={hasMore}
+            isLoadingMore={isLoadingMore}
+            loadingMessage={loadingMessage}
+            sentinelRef={sentinelRef}
+          />
+        </ScrollArea>
+      ) : null}
+
+      {items.length > 0 && viewMode === 'list' ? (
+        <ScrollArea
+          aria-label={listAriaLabel ?? (typeof listLabel === 'string' ? listLabel : 'List')}
+          className={cx('ui-workbench-panel-scroll', 'ui-catalog-browse__list')}
+          data-ui-catalog-browse-list="true"
+          gutter="auto"
+          orientation="vertical"
+          ref={scrollAreaRef}
+        >
+          <List>
+            {items.map((item) => {
+              const selected = selectedItemId === item.id;
+              if (renderListItem) {
+                return <Fragment key={item.id}>{renderListItem(item, { selected })}</Fragment>;
+              }
+
+              return (
+                <ListItem
+                  className="ui-list-item--media"
+                  data-ui-catalog-browse-item={item.id}
+                  description={item.description ?? undefined}
+                  key={item.id}
+                  label={item.label}
+                  leading={
+                    <WorkbenchThumbnail
+                      alt={item.imageAlt ?? item.label}
+                      data-size="library"
+                      fallbackIcon="library"
+                      imageUrl={item.imageUrl ?? null}
+                      size="library"
+                    />
+                  }
+                  meta={item.meta ?? undefined}
+                  onClick={() => onOpenItem(item.id)}
+                  onContextMenu={(event) => {
+                    onItemContextMenu?.(item.id, item.label, event);
+                  }}
+                  onKeyDown={(event) => {
+                    if (event.key === 'Enter' || event.key === ' ') {
+                      event.preventDefault();
+                      onOpenItem(item.id);
+                    }
+                  }}
+                  selected={selected}
+                />
+              );
+            })}
+          </List>
+          <BrowseScrollFooter
+            hasMore={hasMore}
+            isLoadingMore={isLoadingMore}
+            loadingMessage={loadingMessage}
+            sentinelRef={sentinelRef}
+          />
+        </ScrollArea>
+      ) : null}
+    </div>
+  );
+}
+
+function BrowseScrollFooter({
+  hasMore,
+  isLoadingMore,
+  loadingMessage,
+  sentinelRef,
+}: {
+  hasMore: boolean;
+  isLoadingMore: boolean;
+  loadingMessage: string;
+  sentinelRef: RefObject<HTMLDivElement | null>;
+}): ReactNode {
+  if (!hasMore && !isLoadingMore) {
+    return null;
+  }
+
+  return (
+    <>
+      {hasMore ? (
+        <ScrollAreaInfiniteSentinel data-ui-catalog-browse-sentinel="true" ref={sentinelRef} />
+      ) : null}
+      {isLoadingMore ? (
+        <EmptyState compact data-ui-catalog-browse-loading-more="true" icon="loading">
+          {loadingMessage}
+        </EmptyState>
+      ) : null}
+    </>
+  );
+}

package/src/primitives/catalog-browse-pane/catalog-browse-facet-chips.css

@@ -0,0 +1,8 @@
+.ui-catalog-browse-facet-chips {
+  align-items: center;
+  display: flex;
+  flex: 1 1 auto;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+  min-width: 0;
+}

package/src/primitives/catalog-browse-pane/catalog-browse-pane.css

@@ -0,0 +1,84 @@
+.ui-catalog-browse {
+  min-height: 0;
+  min-width: 0;
+}
+
+/* Keep toolbar chrome light — FilterBar already supplies the divider. */
+.ui-catalog-browse > .ui-filter-bar {
+  background: transparent;
+}
+
+.ui-catalog-browse__toolbar {
+  grid-template-columns: minmax(0, 1fr) auto auto;
+  background: transparent;
+}
+
+.ui-catalog-browse__toolbar[data-ui-catalog-browse-has-sort='true'] {
+  grid-template-columns: minmax(0, 1fr) minmax(140px, auto) auto auto;
+}
+
+.ui-catalog-browse__toolbar[data-ui-catalog-browse-toolbar-filter='true'] {
+  grid-template-columns: minmax(0, 1fr) auto auto auto;
+}
+
+.ui-catalog-browse__toolbar[data-ui-catalog-browse-toolbar-filter='true'][data-ui-catalog-browse-has-sort='true'] {
+  grid-template-columns: minmax(0, 1fr) auto minmax(140px, auto) auto auto;
+}
+
+.ui-catalog-browse__search {
+  min-width: 0;
+}
+
+.ui-catalog-browse__search > .ui-clearable-text-input,
+.ui-catalog-browse__search .ui-input[data-width='full'] {
+  width: 100%;
+}
+
+.ui-catalog-browse [data-ui-catalog-browse-sort='true'] {
+  width: var(--ui-catalog-browse-sort-width, 180px);
+  min-width: 140px;
+  max-width: 100%;
+}
+
+.ui-catalog-browse__sort > .ui-select {
+  width: 100%;
+}
+
+.ui-catalog-browse__grid,
+.ui-catalog-browse__list {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.ui-catalog-browse__grid {
+  align-content: start;
+  display: grid;
+  gap: 18px;
+  grid-template-columns: repeat(auto-fill, minmax(164px, 1fr));
+  padding: 12px 8px 20px;
+}
+
+.ui-catalog-browse__grid [data-ui-catalog-browse-sentinel='true'],
+.ui-catalog-browse__grid [data-ui-catalog-browse-loading-more='true'] {
+  grid-column: 1 / -1;
+}
+
+.ui-catalog-browse__list .ui-list-item--media {
+  /* Match WorkbenchThumbnail size="library" so cover art cannot spill into text. */
+  --ui-list-item-media-leading-size: var(--shell-library-capsule-list-width, 116px);
+  min-height: calc(var(--shell-library-capsule-list-height, 43px) + 10px);
+}
+
+.ui-catalog-browse__list .ui-list-item--media .ui-list-item__content {
+  min-width: 0;
+  overflow: hidden;
+}
+
+.ui-catalog-browse__list .ui-list-item--media .ui-list-item__label,
+.ui-catalog-browse__list .ui-list-item--media .ui-list-item__description,
+.ui-catalog-browse__list .ui-list-item--media .ui-list-item__meta {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}

package/src/primitives/catalog-browse-pane/filterCatalogBrowseItems.ts

@@ -0,0 +1,27 @@
+import type { CatalogBrowseItem } from './CatalogBrowsePane';
+
+/**
+ * Client-side text match for catalog rows — label, meta, and description.
+ * Hosts own domain filtering; use this after mapping to `CatalogBrowseItem`.
+ */
+export function matchCatalogBrowseItem(item: CatalogBrowseItem, query: string): boolean {
+  const normalized = query.trim().toLowerCase();
+  if (normalized.length === 0) {
+    return true;
+  }
+  const haystacks = [item.label, item.meta, item.description];
+  return haystacks.some(
+    (value) => typeof value === 'string' && value.toLowerCase().includes(normalized),
+  );
+}
+
+export function filterCatalogBrowseItems(
+  items: ReadonlyArray<CatalogBrowseItem>,
+  query: string,
+): CatalogBrowseItem[] {
+  const normalized = query.trim();
+  if (normalized.length === 0) {
+    return [...items];
+  }
+  return items.filter((item) => matchCatalogBrowseItem(item, normalized));
+}

package/src/primitives/catalog-browse-pane/index.ts

@@ -0,0 +1,3 @@
+export * from './CatalogBrowseFacetChips';
+export * from './CatalogBrowsePane';
+export * from './filterCatalogBrowseItems';

package/src/primitives/catalog-filter-overlay/CatalogFilterOverlay.tsx

@@ -0,0 +1,73 @@
+import './catalog-filter-overlay.css';
+import type { ComponentPropsWithRef, ReactNode, Ref } from 'react';
+
+import { cx } from '../../utils/cx';
+import { IconButton } from '../icon-button/IconButton';
+
+export interface CatalogFilterOverlayProps extends Omit<
+  ComponentPropsWithRef<'div'>,
+  'children' | 'title'
+> {
+  readonly children: ReactNode;
+  /**
+   * When true, Clear stays mounted and sized but is not actionable.
+   * Keeps the title row height stable across selection changes.
+   */
+  readonly clearDisabled?: boolean | undefined;
+  readonly clearLabel: string;
+  readonly onClear: () => void;
+  readonly ref?: Ref<HTMLDivElement> | undefined;
+  readonly title: ReactNode;
+  readonly titleId: string;
+}
+
+/**
+ * Presentational filter overlay shell: elevated surface, fixed-height header
+ * (title + Clear), and a body slot for facet sections.
+ * Hosts own portal mounting, positioning, and product copy — prefer
+ * `useAnchoredOverlayPanel` / `measureAnchoredOverlayPanel` from
+ * `@workbench-kit/react/overlay` for trigger-relative placement, dismiss,
+ * remeasure, and portal root (keeps nested SearchableMultiSelect listboxes
+ * inside the dismiss boundary).
+ */
+export function CatalogFilterOverlay({
+  children,
+  className,
+  clearDisabled = false,
+  clearLabel,
+  onClear,
+  ref,
+  title,
+  titleId,
+  ...props
+}: CatalogFilterOverlayProps) {
+  return (
+    <div
+      {...props}
+      ref={ref}
+      aria-labelledby={titleId}
+      className={cx('ui-catalog-filter-overlay', className)}
+      data-ui-catalog-filter-overlay="true"
+      role="dialog"
+    >
+      <header className="ui-catalog-filter-overlay__header">
+        <h2 className="ui-catalog-filter-overlay__title" id={titleId}>
+          {title}
+        </h2>
+        <IconButton
+          className="ui-catalog-filter-overlay__clear"
+          compact
+          disabled={clearDisabled}
+          icon="codicon-clear-all"
+          label={clearLabel}
+          onClick={() => {
+            if (!clearDisabled) {
+              onClear();
+            }
+          }}
+        />
+      </header>
+      <div className="ui-catalog-filter-overlay__body">{children}</div>
+    </div>
+  );
+}

package/src/primitives/catalog-filter-overlay/catalog-filter-overlay.css

@@ -0,0 +1,65 @@
+.ui-catalog-filter-overlay {
+  --ui-catalog-filter-overlay-pad-x: 0.75rem;
+  /* Cap at 4px: baseline --radius-sm can be 6px. */
+  --ui-catalog-filter-overlay-radius: min(4px, var(--shell-radius-control, 4px));
+  z-index: 80;
+  display: flex;
+  min-width: 20rem;
+  max-width: min(23.75rem, calc(100vw - 1rem));
+  flex-direction: column;
+  /* Opt in when portaled into a pointer-events:none host (workbench overlays). */
+  pointer-events: auto;
+  overflow: hidden;
+  border: 1px solid var(--vscode-widget-border, var(--color-border-default, var(--color-border)));
+  border-radius: var(--ui-catalog-filter-overlay-radius);
+  background: var(
+    --vscode-menu-background,
+    var(--color-surface-elevated, var(--color-surface-secondary, #2d2d2d))
+  );
+  /* Explicit fallbacks: overlay is often portaled outside [data-theme]. */
+  color: var(--vscode-foreground, var(--color-text-primary, var(--color-text, #cccccc)));
+  box-shadow:
+    0 0.125rem 0.25rem rgb(0 0 0 / 12%),
+    0 0.75rem 1.75rem rgb(0 0 0 / 22%);
+}
+
+.ui-catalog-filter-overlay__header {
+  box-sizing: border-box;
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: 0.375rem;
+  min-width: 0;
+  /* Compact IconButton + vertical padding — stable whether Clear is enabled. */
+  min-height: calc(var(--ui-icon-button-size-compact, 1.5rem) + 1rem);
+  padding: 0.5rem var(--ui-catalog-filter-overlay-pad-x);
+  border-bottom: 1px solid
+    var(--vscode-widget-border, var(--color-border-subtle, var(--color-border)));
+}
+
+.ui-catalog-filter-overlay__title {
+  flex: 1 1 auto;
+  min-width: 0;
+  margin: 0;
+  overflow: hidden;
+  color: var(--vscode-foreground, var(--color-text-primary, var(--color-text)));
+  font-size: 0.8125rem;
+  font-weight: 650;
+  letter-spacing: 0.01em;
+  line-height: 1.3;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ui-catalog-filter-overlay__clear {
+  flex: 0 0 auto;
+  margin-inline-start: auto;
+}
+
+.ui-catalog-filter-overlay__body {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-height: 0;
+  overflow: hidden;
+}

package/src/primitives/catalog-filter-overlay/index.ts

@@ -0,0 +1 @@
+export * from './CatalogFilterOverlay';

package/src/primitives/checkbox/Checkbox.tsx

@@ -0,0 +1,40 @@
+import './checkbox.css';
+import type { ChangeEvent, ComponentPropsWithRef, ReactNode } from 'react';
+import { cx } from '../../utils/cx';
+
+export interface CheckboxProps extends Omit<ComponentPropsWithRef<'input'>, 'type'> {
+  label?: ReactNode | undefined;
+  onCheckedChange?: (checked: boolean, event: ChangeEvent<HTMLInputElement>) => void;
+}
+
+export function Checkbox({
+  className,
+  disabled,
+  label,
+  onChange,
+  onCheckedChange,
+  ...props
+}: CheckboxProps) {
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    onChange?.(event);
+    onCheckedChange?.(event.currentTarget.checked, event);
+  };
+
+  return (
+    <label className={cx('ui-checkbox', className)} data-disabled={disabled ? 'true' : undefined}>
+      <span className="ui-checkbox__control">
+        <input
+          className="ui-checkbox__input"
+          disabled={disabled}
+          type="checkbox"
+          onChange={handleChange}
+          {...props}
+        />
+        <span aria-hidden="true" className="ui-checkbox__indicator" />
+      </span>
+      {label !== undefined && label !== null && label !== '' ? (
+        <span className="ui-checkbox__label">{label}</span>
+      ) : null}
+    </label>
+  );
+}