@flamingo-stack/openframe-frontend-core 0.0.764 → 0.0.766

package/src/components/loading/unified-skeleton.tsx

@@ -1,8 +1,16 @@
 import type React from 'react';
+import { TEXT_LINES_HEIGHT } from '../../styles/component-sizes';
 import { cn } from '../../utils/cn';
+import { BUTTON_SIZE_CLASS, type ButtonSizeKey } from '../ui/button/button-styles';
+import { INPUT_HEIGHT_CLASS, INPUT_RADIUS_CLASS } from '../ui/input-styles';
 import { SKELETON_SURFACE_CLASS } from '../ui/skeleton-surface';
 
-interface UnifiedSkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
+interface UnifiedSkeletonProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /**
+   * A skeleton is a shape, never a frame: it takes no children, so nothing (another skeleton above all) is ever
+   * drawn inside its pulsing surface.
+   */
+  children?: never;
   className?: string;
   variant?: 'default' | 'text' | 'circular' | 'rectangular';
   width?: string | number;
@@ -31,8 +39,8 @@ interface UnifiedSkeletonProps extends React.HTMLAttributes<HTMLDivElement> {
  * Base skeleton component with consistent styling across the application.
  *
  * Design Specifications:
- * - Color: #2A2A2A base with #3A3A3A pulse highlight
- * - Animation: 1.5s pulse duration, ease-in-out timing
+ * - Surface: `SKELETON_SURFACE_CLASS` (`ui/skeleton-surface.ts`), the ONE skeleton surface: the ODS skeleton token
+ *   and the ONE pulse every loading state shares. Never a second colour, duration or animation.
  * - Responsive: Mobile-first approach with proper scaling
  * - Accessibility: hidden from assistive technology (the `LoadingRegion` around it announces), reduced motion support
  *
@@ -80,9 +88,11 @@ export function UnifiedSkeleton({
       className ?? '',
     );
 
+  // The caller's style is kept (a held image's aspect ratio); the width and height props win where given.
   const style: React.CSSProperties = {
-    width: width,
-    height: height,
+    ...props.style,
+    ...(width !== undefined && { width }),
+    ...(height !== undefined && { height }),
   };
 
   return (
@@ -96,17 +106,83 @@ export function UnifiedSkeleton({
         !width && !style.width && variant !== 'circular' && 'w-full',
         className,
       )}
-      style={style}
       // A bar is decoration: hidden from assistive technology unless the caller names what is loading.
       // The loading CONTAINER says it once (`LoadingRegion`: aria-busy plus one polite status).
       {...(ariaLabel ? { role: 'status', 'aria-label': ariaLabel } : { 'aria-hidden': true })}
       {...props}
+      style={style}
     />
   );
 }
 
 /**
- * Text skeleton variants for consistent typography loading
+ * The ODS type steps a text line can take, as static classes (a class built at runtime emits no CSS). `inherit` sets
+ * no type of its own: the bar takes the line height of the element it sits in (a row sized by its caller).
+ */
+const TEXT_LINE_TYPE = {
+  h1: 'text-h1',
+  h2: 'text-h2',
+  h3: 'text-h3',
+  h4: 'text-h4',
+  h5: 'text-h5',
+  h6: 'text-h6',
+  code: 'text-code',
+  inherit: '',
+} as const;
+
+export type TextLineType = keyof typeof TEXT_LINE_TYPE;
+
+export interface TextLineSkeletonProps {
+  /** The type step of the text the bar stands for (`inherit`: the surrounding element's). */
+  type: TextLineType;
+  /** How many lines the text takes (1 by default). Past 6, the height is set inline in `lh`. */
+  lines?: number;
+  /**
+   * `span` for a bar inside phrasing content (a `<p>`, a heading, a label): a `<div>` there is invalid HTML, and
+   * the browser's parser closes the `<p>` around it, adding empty paragraphs that take a flex gap each.
+   */
+  as?: 'div' | 'span';
+  /**
+   * The bar's width as an inline style, for a width a static class cannot state (a `ch` count per item: `'12ch'`).
+   * A class in `className` is the usual way.
+   */
+  width?: string | number;
+  className?: string;
+}
+
+/**
+ * THE text bar: a run of text lines while it loads. The bar takes the type step the loaded text uses and `lines` of
+ * its line height (`lh`), so the loaded text takes its place at every breakpoint without moving the page. Never
+ * rebuild it as a `UnifiedSkeleton` with `h-[1lh]`.
+ */
+export function TextLineSkeleton({ type, lines = 1, as = 'div', width, className }: TextLineSkeletonProps) {
+  const Tag = as;
+  const heightClass = (TEXT_LINES_HEIGHT as Record<number, string>)[lines];
+  // A run of separate lines, like the text it stands for: each line is one line-height row holding a bar narrower
+  // than the row (the gap between bars is the leading), and a paragraph's last line is shorter. The box is exactly
+  // `lines` line heights, so the loaded text takes its place without moving the page.
+  return (
+    <Tag
+      aria-hidden="true"
+      className={cn('flex flex-col', TEXT_LINE_TYPE[type], heightClass, className)}
+      style={heightClass && width === undefined ? undefined : { height: heightClass ? undefined : `${lines}lh`, width }}
+    >
+      {Array.from({ length: lines }, (_, index) => (
+        <Tag key={index} className="flex h-[1lh] items-center">
+          <UnifiedSkeleton
+            as={as}
+            className={cn('block h-[0.7lh] rounded', lines > 1 && index === lines - 1 ? 'w-3/5' : 'w-full')}
+          />
+        </Tag>
+      ))}
+    </Tag>
+  );
+}
+
+/**
+ * Text skeleton variants at fixed heights. A skeleton that must take exactly
+ * the space of the text it stands for (a card whose loaded and loading boxes
+ * are one size) is `TextLineSkeleton`, sized by the text's own type step.
  */
 export const TextSkeleton = {
   /**
@@ -141,14 +217,24 @@ export const TextSkeleton = {
 /**
  * Interactive element skeletons
  */
+/** The width a button skeleton stands for its label with (a short label). */
+const BUTTON_SKELETON_LABEL_WIDTH_CLASS = 'w-24';
+
 export const InteractiveSkeleton = {
   /**
-   * Button skeleton with proper touch targets
+   * A button while its label is read (or a whole button row in a skeleton): the box is that Button size's own
+   * classes (`BUTTON_SIZE_CLASS`, the same map `buttonVariants` reads: height and padding per breakpoint; the
+   * `default` size when none is given, as `Button`'s own default) and a width standing for the label (`className`
+   * overrides it); icon sizes carry their own width.
    */
-  Button: ({ className, ...props }: Omit<UnifiedSkeletonProps, 'variant'>) => (
+  Button: ({
+    className,
+    size = 'default',
+    ...props
+  }: Omit<UnifiedSkeletonProps, 'variant'> & { size?: ButtonSizeKey }) => (
     <UnifiedSkeleton
       variant="default"
-      className={cn('h-10 w-32 content-md:h-12 content-md:w-40', className)}
+      className={cn(BUTTON_SIZE_CLASS[size], !size.startsWith('icon') && BUTTON_SKELETON_LABEL_WIDTH_CLASS, className)}
       {...props}
     />
   ),
@@ -157,7 +243,11 @@ export const InteractiveSkeleton = {
    * Input field skeleton
    */
   Input: ({ className, ...props }: Omit<UnifiedSkeletonProps, 'variant'>) => (
-    <UnifiedSkeleton variant="default" className={cn('h-10 w-full content-md:h-12', className)} {...props} />
+    <UnifiedSkeleton
+      variant="default"
+      className={cn('w-full', INPUT_HEIGHT_CLASS, INPUT_RADIUS_CLASS, className)}
+      {...props}
+    />
   ),
 
   /**

package/src/components/log-severity-dot.tsx

@@ -1,29 +1,32 @@
 import { forwardRef } from 'react';
 import { type LogSeverityDotProps, LOG_SEVERITY_COLORS, LOG_SEVERITY_LABELS } from '../types/logs.types';
 import { cn } from '../utils/cn';
+import { UnifiedSkeleton } from './loading/unified-skeleton';
 
-export const LogSeverityDot = forwardRef<HTMLDivElement, LogSeverityDotProps>(
-  ({ severity, size = 'md', className }, ref) => {
-    const sizeClasses = {
-      sm: 'w-4 h-4',
-      md: 'w-6 h-6',
-      lg: 'w-8 h-8',
-    };
+/** The dot's box and the dot inside it, per size, read by the dot and by its skeleton. */
+const SEVERITY_BOX_CLASS = { sm: 'w-4 h-4', md: 'w-6 h-6', lg: 'w-8 h-8' } as const;
+const SEVERITY_DOT_CLASS = { sm: 'w-2 h-2', md: 'w-3 h-3', lg: 'w-4 h-4' } as const;
+const SEVERITY_FRAME_CLASS = 'relative flex shrink-0 items-center justify-center';
 
-    const dotSizeClasses = {
-      sm: 'w-2 h-2',
-      md: 'w-3 h-3',
-      lg: 'w-4 h-4',
-    };
+/** The dot while its log is read: the dot's own box, the dot a circle of the dot's size. */
+export function LogSeverityDotSkeleton({ size = 'md', className }: Pick<LogSeverityDotProps, 'size' | 'className'>) {
+  return (
+    <span className={cn(SEVERITY_FRAME_CLASS, SEVERITY_BOX_CLASS[size], className)} aria-hidden>
+      <UnifiedSkeleton variant="circular" className={SEVERITY_DOT_CLASS[size]} />
+    </span>
+  );
+}
 
+export const LogSeverityDot = forwardRef<HTMLDivElement, LogSeverityDotProps>(
+  ({ severity, size = 'md', className }, ref) => {
     return (
       <div
         ref={ref}
-        className={cn('relative flex shrink-0 items-center justify-center', sizeClasses[size], className)}
+        className={cn(SEVERITY_FRAME_CLASS, SEVERITY_BOX_CLASS[size], className)}
         aria-label={`${LOG_SEVERITY_LABELS[severity]} severity`}
       >
         <div
-          className={cn('rounded-full', dotSizeClasses[size])}
+          className={cn('rounded-full', SEVERITY_DOT_CLASS[size])}
           style={{ backgroundColor: LOG_SEVERITY_COLORS[severity] }}
         />
       </div>

package/src/components/logs-list.tsx

@@ -2,13 +2,42 @@ import { type FC, forwardRef, useRef } from 'react';
 import type { LogsListProps, LogEntry } from '../types/logs.types';
 import { cn } from '../utils/cn';
 import { formatDateTimeYmd } from '../utils/format';
-import { LogSeverityDot } from './log-severity-dot';
+import { LoadingRegion } from './loading/loading-region';
+import { TextLineSkeleton } from './loading/unified-skeleton';
+import { LogSeverityDot, LogSeverityDotSkeleton } from './log-severity-dot';
 import { ToolIcon } from './tool-icon';
 
 // UTC-pinned so the server and every client agree (React #418), through the one
 // renderer rather than hand-built `getUTC*` strings.
 const formatTimestamp = (timestamp: string | Date): string => formatDateTimeYmd(timestamp, null, { separator: ',' });
 
+/** The log row's layout, read by the row and by its skeleton, so the skeleton is the row's size. */
+const LOG_ROW_CLASS = 'relative box-border flex w-full items-start gap-3 rounded px-1 py-2';
+const LOG_ROW_TEXT_CLASS = 'min-w-0 flex-1 space-y-1';
+const LOG_META_ROW_CLASS = 'flex items-center gap-2';
+const LOG_SCROLL_CLASS = 'flex-1 overflow-y-auto px-4 py-3';
+const LOG_FRAME_CLASS = 'relative flex flex-col overflow-hidden rounded-lg border border-ods-border bg-ods-card';
+/**
+ * Rows the list's skeleton draws: one screen of the list's default 400px box (a row is a `text-h6` title over a
+ * `text-h5` time, about 60px with its padding).
+ */
+const LOGS_LIST_FOLD = 6;
+
+/** A log row while it is read: the severity dot's box, the title and the time as bars. */
+function LogCardSkeleton() {
+  return (
+    <div className={LOG_ROW_CLASS} aria-hidden>
+      <LogSeverityDotSkeleton size="md" />
+      <div className={LOG_ROW_TEXT_CLASS}>
+        <TextLineSkeleton type="h6" className="w-3/4" />
+        <div className={LOG_META_ROW_CLASS}>
+          <TextLineSkeleton type="h5" className="w-32" />
+        </div>
+      </div>
+    </div>
+  );
+}
+
 const LogCard: FC<{
   log: LogEntry;
   isLast: boolean;
@@ -18,10 +47,7 @@ const LogCard: FC<{
   return (
     <div className="relative">
       <div
-        className={cn(
-          'relative box-border flex w-full items-start gap-3 rounded px-1 py-2',
-          'cursor-pointer transition-colors hover:bg-ods-bg-hover/50',
-        )}
+        className={cn(LOG_ROW_CLASS, 'cursor-pointer transition-colors hover:bg-ods-bg-hover/50')}
         onClick={onClick}
         role="button"
         tabIndex={0}
@@ -34,9 +60,9 @@ const LogCard: FC<{
       >
         <LogSeverityDot severity={log.severity} size="md" />
 
-        <div className="min-w-0 flex-1 space-y-1">
+        <div className={LOG_ROW_TEXT_CLASS}>
           <p className="text-ods-text-primary text-h6">{log.title}</p>
-          <div className="flex items-center gap-2">
+          <div className={LOG_META_ROW_CLASS}>
             <p className="text-ods-text-secondary text-h5">{formatTimestamp(log.timestamp)}</p>
             {log.toolType && <ToolIcon toolType={log.toolType} size={16} />}
           </div>
@@ -85,18 +111,15 @@ export const LogsList = forwardRef<HTMLDivElement, LogsListProps>(
     };
 
     if (loading) {
+      // The list's own frame and scroller with a screen of row skeletons.
       return (
-        <div
-          ref={ref}
-          className={cn(
-            'rounded-lg border border-ods-border bg-ods-card p-4',
-            'flex items-center justify-center',
-            getContainerClasses(),
-            className,
-          )}
-          style={getContainerStyles()}
-        >
-          <div className="text-ods-text-muted text-h6">Loading logs...</div>
+        <div ref={ref} className={cn(LOG_FRAME_CLASS, getContainerClasses(), className)} style={getContainerStyles()}>
+          <LoadingRegion label="Loading logs" className={LOG_SCROLL_CLASS}>
+            {Array.from({ length: LOGS_LIST_FOLD }, (_, i) => (
+              // biome-ignore lint/suspicious/noArrayIndexKey: skeleton rows never reorder
+              <LogCardSkeleton key={i} />
+            ))}
+          </LoadingRegion>
         </div>
       );
     }
@@ -119,17 +142,8 @@ export const LogsList = forwardRef<HTMLDivElement, LogsListProps>(
     }
 
     return (
-      <div
-        ref={ref}
-        className={cn(
-          'relative rounded-lg border border-ods-border bg-ods-card',
-          'flex flex-col overflow-hidden',
-          getContainerClasses(),
-          className,
-        )}
-        style={getContainerStyles()}
-      >
-        <div ref={containerRef} className="flex-1 overflow-y-auto px-4 py-3">
+      <div ref={ref} className={cn(LOG_FRAME_CLASS, getContainerClasses(), className)} style={getContainerStyles()}>
+        <div ref={containerRef} className={LOG_SCROLL_CLASS}>
           {logs.map((log, index) => (
             <LogCard
               key={log.id}

package/src/components/media-carousel.tsx

@@ -343,7 +343,3 @@ export const MediaCarousel = memo(function MediaCarouselImpl({
     </div>
   );
 });
-
-// The carousel's item shape is the lib-wide SSOT — re-exported here so hub
-// code can `import type { MediaItem } from '.../components'`.
-export type { MediaItem };