@furystack/shades-common-components 12.0.1 → 12.2.0

package/src/components/cache-view.spec.tsx

@@ -0,0 +1,210 @@
+import { Cache } from '@furystack/cache'
+import type { CacheResult, CacheWithValue } from '@furystack/cache'
+import { Shade, createComponent, flushUpdates } from '@furystack/shades'
+import { sleepAsync } from '@furystack/utils'
+import { describe, expect, it, vi } from 'vitest'
+import { CacheView } from './cache-view.js'
+
+const TestContent = Shade<{ data: CacheWithValue<string> }>({
+  shadowDomName: 'test-cache-content',
+  render: ({ props }) => <span className="content-value">{props.data.value}</span>,
+})
+
+const renderCacheView = async (
+  cache: Cache<string, [string]>,
+  args: [string],
+  options?: {
+    loader?: JSX.Element
+    error?: (error: unknown, retry: () => void) => JSX.Element
+  },
+) => {
+  const el = (
+    <div>
+      <CacheView cache={cache} args={args} content={TestContent} loader={options?.loader} error={options?.error} />
+    </div>
+  )
+  const cacheView = el.firstElementChild as JSX.Element
+  cacheView.updateComponent()
+  await flushUpdates()
+  return { container: el, cacheView }
+}
+
+describe('CacheView', () => {
+  it('should be defined', () => {
+    expect(CacheView).toBeDefined()
+    expect(typeof CacheView).toBe('function')
+  })
+
+  it('should create a cache-view element', () => {
+    const cache = new Cache<string, [string]>({ load: async (key) => key })
+    const el = (<CacheView cache={cache} args={['test']} content={TestContent} />) as unknown as HTMLElement
+    expect(el).toBeDefined()
+    expect(el.tagName?.toLowerCase()).toBe('shade-cache-view')
+    cache[Symbol.dispose]()
+  })
+
+  describe('loading state', () => {
+    it('should render null by default when loading', async () => {
+      const cache = new Cache<string, [string]>({
+        load: () => new Promise(() => {}),
+      })
+      const { cacheView } = await renderCacheView(cache, ['test'])
+      expect(cacheView.querySelector('test-cache-content')).toBeNull()
+      expect(cacheView.querySelector('shade-result')).toBeNull()
+      cache[Symbol.dispose]()
+    })
+
+    it('should render custom loader when provided', async () => {
+      const cache = new Cache<string, [string]>({
+        load: () => new Promise(() => {}),
+      })
+      const { cacheView } = await renderCacheView(cache, ['test'], {
+        loader: (<span className="custom-loader">Loading...</span>) as unknown as JSX.Element,
+      })
+      const loader = cacheView.querySelector('.custom-loader')
+      expect(loader).not.toBeNull()
+      expect(loader?.textContent).toBe('Loading...')
+      cache[Symbol.dispose]()
+    })
+  })
+
+  describe('loaded state', () => {
+    it('should render content when cache has loaded value', async () => {
+      const cache = new Cache<string, [string]>({ load: async (key) => `Hello ${key}` })
+      await cache.get('world')
+      const { cacheView } = await renderCacheView(cache, ['world'])
+      const contentEl = cacheView.querySelector('test-cache-content')
+      expect(contentEl).not.toBeNull()
+      const contentComponent = contentEl as JSX.Element
+      contentComponent.updateComponent()
+      await flushUpdates()
+      const valueEl = contentComponent.querySelector('.content-value')
+      expect(valueEl?.textContent).toBe('Hello world')
+      cache[Symbol.dispose]()
+    })
+  })
+
+  describe('failed state', () => {
+    it('should render default error UI when cache has failed', async () => {
+      const cache = new Cache<string, [string]>({
+        load: async () => {
+          throw new Error('Test failure')
+        },
+      })
+      try {
+        await cache.get('test')
+      } catch {
+        // expected
+      }
+      const { cacheView } = await renderCacheView(cache, ['test'])
+      const resultEl = cacheView.querySelector('shade-result')
+      expect(resultEl).not.toBeNull()
+      const resultComponent = resultEl as JSX.Element
+      resultComponent.updateComponent()
+      await flushUpdates()
+      expect(resultComponent.querySelector('.result-title')?.textContent).toBe('Something went wrong')
+      cache[Symbol.dispose]()
+    })
+
+    it('should render custom error UI when error prop is provided', async () => {
+      const cache = new Cache<string, [string]>({
+        load: async () => {
+          throw new Error('Custom failure')
+        },
+      })
+      try {
+        await cache.get('test')
+      } catch {
+        // expected
+      }
+      const customError = vi.fn(
+        (err: unknown, _retry: () => void) =>
+          (<span className="custom-error">{String(err)}</span>) as unknown as JSX.Element,
+      )
+      const { cacheView } = await renderCacheView(cache, ['test'], { error: customError })
+      expect(customError).toHaveBeenCalledOnce()
+      expect(customError.mock.calls[0][0]).toBeInstanceOf(Error)
+      const customErrorEl = cacheView.querySelector('.custom-error')
+      expect(customErrorEl).not.toBeNull()
+      cache[Symbol.dispose]()
+    })
+
+    it('should not render content when failed even if stale value exists', async () => {
+      const cache = new Cache<string, [string]>({ load: async (key) => key })
+      await cache.get('test')
+      cache.setExplicitValue({
+        loadArgs: ['test'],
+        value: { status: 'failed', error: new Error('fail'), value: 'stale', updatedAt: new Date() },
+      })
+      const { cacheView } = await renderCacheView(cache, ['test'])
+      expect(cacheView.querySelector('test-cache-content')).toBeNull()
+      expect(cacheView.querySelector('shade-result')).not.toBeNull()
+      cache[Symbol.dispose]()
+    })
+
+    it('should call cache.reload when retry is invoked', async () => {
+      const loadFn = vi.fn<(key: string) => Promise<string>>(async () => {
+        throw new Error('fail')
+      })
+      const cache = new Cache<string, [string]>({ load: loadFn })
+      try {
+        await cache.get('test')
+      } catch {
+        // expected
+      }
+      let capturedRetry: (() => void) | undefined
+      const customError = (_err: unknown, retry: () => void) => {
+        capturedRetry = retry
+        return (<span className="custom-error">Error</span>) as unknown as JSX.Element
+      }
+      await renderCacheView(cache, ['test'], { error: customError })
+      expect(capturedRetry).toBeDefined()
+
+      loadFn.mockResolvedValueOnce('recovered')
+      capturedRetry!()
+      await sleepAsync(50)
+
+      const observable = cache.getObservable('test')
+      const result = observable.getValue()
+      expect(result.status).toBe('loaded')
+      expect(result.value).toBe('recovered')
+      cache[Symbol.dispose]()
+    })
+  })
+
+  describe('obsolete state', () => {
+    it('should render content when obsolete and trigger reload', async () => {
+      const loadFn = vi.fn(async (key: string) => `Hello ${key}`)
+      const cache = new Cache<string, [string]>({ load: loadFn })
+      await cache.get('test')
+      cache.setObsolete('test')
+
+      const { cacheView } = await renderCacheView(cache, ['test'])
+      const contentEl = cacheView.querySelector('test-cache-content')
+      expect(contentEl).not.toBeNull()
+
+      await sleepAsync(50)
+      // reload should have been called (initial load + obsolete reload)
+      expect(loadFn).toHaveBeenCalledTimes(2)
+      cache[Symbol.dispose]()
+    })
+  })
+
+  describe('error takes priority over value', () => {
+    it('should show error when failed with value, not content', async () => {
+      const cache = new Cache<string, [string]>({ load: async (key) => key })
+      await cache.get('test')
+      const failedWithValue: CacheResult<string> = {
+        status: 'failed',
+        error: new Error('whoops'),
+        value: 'stale-data',
+        updatedAt: new Date(),
+      }
+      cache.setExplicitValue({ loadArgs: ['test'], value: failedWithValue })
+      const { cacheView } = await renderCacheView(cache, ['test'])
+      expect(cacheView.querySelector('test-cache-content')).toBeNull()
+      expect(cacheView.querySelector('shade-result')).not.toBeNull()
+      cache[Symbol.dispose]()
+    })
+  })
+})

package/src/components/cache-view.tsx

@@ -0,0 +1,103 @@
+import type { Cache, CacheWithValue } from '@furystack/cache'
+import { hasCacheValue, isFailedCacheResult, isObsoleteCacheResult } from '@furystack/cache'
+import type { ShadeComponent } from '@furystack/shades'
+import { Shade, createComponent } from '@furystack/shades'
+
+import { Button } from './button.js'
+import { Result } from './result.js'
+
+/**
+ * Props for the CacheView component.
+ * @typeParam TData - The type of data stored in the cache
+ * @typeParam TArgs - The tuple type of arguments used to identify the cache entry
+ */
+export type CacheViewProps<TData, TArgs extends any[]> = {
+  /** The cache instance to observe and control */
+  cache: Cache<TData, TArgs>
+  /** The arguments identifying which cache entry to display */
+  args: TArgs
+  /** Shades component rendered when a value is available (loaded or obsolete). Receives CacheWithValue<TData>. */
+  content: ShadeComponent<{ data: CacheWithValue<TData> }>
+  /** Optional custom loader element. Default: null (nothing shown when loading). */
+  loader?: JSX.Element
+  /**
+   * Optional custom error UI. Receives the error and a retry callback.
+   * The retry callback calls cache.reload(...args).
+   * If not provided, a default Result + retry Button is shown.
+   */
+  error?: (error: unknown, retry: () => void) => JSX.Element
+}
+
+const getDefaultErrorUi = (error: unknown, retry: () => void): JSX.Element =>
+  (
+    <Result status="error" title="Something went wrong" subtitle={String(error)}>
+      <Button variant="outlined" onclick={retry}>
+        Retry
+      </Button>
+    </Result>
+  ) as unknown as JSX.Element
+
+/**
+ * CacheView renders the state of a cache entry for the given cache + args.
+ *
+ * It subscribes to the cache observable and handles all states:
+ * 1. **Error first** - If the cache entry has failed, shows the error UI with a retry button.
+ * 2. **Value next** - If the entry has a value (loaded or obsolete), renders the content component.
+ *    When obsolete, it also triggers a reload automatically.
+ * 3. **Loading last** - If there is no value and no error, shows the loader (or null by default).
+ *
+ * @example
+ * ```tsx
+ * const MyContent = Shade<{ data: CacheWithValue<User> }>({
+ *   shadowDomName: 'my-content',
+ *   render: ({ props }) => <div>{props.data.value.name}</div>,
+ * })
+ *
+ * <CacheView cache={userCache} args={[userId]} content={MyContent} />
+ * ```
+ */
+export const CacheView: <TData, TArgs extends any[]>(props: CacheViewProps<TData, TArgs>) => JSX.Element = Shade({
+  shadowDomName: 'shade-cache-view',
+  render: ({ props, useObservable, useState }): JSX.Element | null => {
+    const { cache, args, content, loader, error } = props
+
+    const argsKey = JSON.stringify(args)
+    const observable = cache.getObservable(...args)
+
+    const [result] = useObservable(`cache-${argsKey}`, observable)
+
+    const [lastReloadedArgsKey, setLastReloadedArgsKey] = useState<string | null>('lastReloadedArgsKey', null)
+
+    const retry = () => {
+      cache.reload(...args).catch(() => {
+        /* error state will be set by cache */
+      })
+    }
+
+    // 1. Error first
+    if (isFailedCacheResult(result)) {
+      const errorRenderer = error ?? getDefaultErrorUi
+      return errorRenderer(result.error, retry)
+    }
+
+    // 2. Value next
+    if (hasCacheValue(result)) {
+      if (isObsoleteCacheResult(result)) {
+        if (lastReloadedArgsKey !== argsKey) {
+          setLastReloadedArgsKey(argsKey)
+          cache.reload(...args).catch(() => {
+            /* error state will be set by cache */
+          })
+        }
+      } else if (lastReloadedArgsKey !== null) {
+        setLastReloadedArgsKey(null)
+      }
+      return createComponent(content as ShadeComponent<{ data: CacheWithValue<unknown> }>, {
+        data: result,
+      }) as unknown as JSX.Element
+    }
+
+    // 3. Loading last
+    return loader ?? null
+  },
+})

package/src/components/icons/icon-definitions.spec.ts

@@ -1,11 +1,14 @@
 import { describe, expect, it } from 'vitest'
 import * as allIcons from './icon-definitions.js'
+import type { IconCategory } from './icon-types.js'
 
 const iconEntries = Object.entries(allIcons)
 
+const validCategories: IconCategory[] = ['Actions', 'Navigation', 'Status', 'Content', 'UI', 'Common']
+
 describe('Icon definitions', () => {
-  it('should export at least 50 icons', () => {
-    expect(iconEntries.length).toBeGreaterThanOrEqual(50)
+  it('should export at least 100 icons', () => {
+    expect(iconEntries.length).toBeGreaterThanOrEqual(100)
   })
 
   describe.each(iconEntries)('%s', (_name, icon) => {
@@ -46,6 +49,29 @@ describe('Icon definitions', () => {
         }
       }
     })
+
+    it('should have a non-empty name', () => {
+      expect(typeof icon.name).toBe('string')
+      expect(icon.name!.length).toBeGreaterThan(0)
+    })
+
+    it('should have a non-empty description', () => {
+      expect(typeof icon.description).toBe('string')
+      expect(icon.description!.length).toBeGreaterThan(0)
+    })
+
+    it('should have at least one keyword', () => {
+      expect(Array.isArray(icon.keywords)).toBe(true)
+      expect(icon.keywords!.length).toBeGreaterThanOrEqual(1)
+      for (const kw of icon.keywords!) {
+        expect(typeof kw).toBe('string')
+        expect(kw.length).toBeGreaterThan(0)
+      }
+    })
+
+    it('should have a valid category', () => {
+      expect(validCategories).toContain(icon.category)
+    })
   })
 
   it('should not have duplicate path data across different icons', () => {