@krapwoo/ds-viewer 0.3.0 → 0.4.1

package/native/catalog/CatalogShell.tsx

@@ -1,11 +1,16 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { AccessibilityInfo, Platform, ScrollView, StyleSheet, Text, View, findNodeHandle } from 'react-native';
+import { AccessibilityInfo, Platform, Pressable, ScrollView, StyleSheet, Text, View, findNodeHandle } from 'react-native';
 import type { ImageSourcePropType } from 'react-native';
-import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_MAX_CONTENT_WIDTH, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_MAX_CONTENT_WIDTH, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { CatalogSidebar } from './CatalogSidebar';
 import { SectionBlock } from './SectionBlock';
-import { groupLabelFor, hashForId, idFromHash, neighbors, orderedIds } from './catalogNavigation';
-import type { NavGroup, PreviewWidths, SectionDef } from './types';
+import { UpdatePanel } from './UpdatePanel';
+import { groupLabelFor, hashForId, neighbors, orderedIds, resolveActiveFromHash, shouldShowMajorBanner, footerLabel, UPDATE_PAGE_ID } from './catalogNavigation';
+import type { NavGroup, PreviewWidths, SectionDef, UpdateNotice } from './types';
+
+/** `active` can be a real page id, or the reserved update-page id — never both a generic `TId`
+ *  constraint and a hardcoded string literal type at once, which is why this is its own alias. */
+type ShellPageId<TId extends string> = TId | typeof UPDATE_PAGE_ID;
 
 function isWeb(): boolean {
   return Platform.OS === 'web' && typeof window !== 'undefined';
@@ -36,6 +41,62 @@ function resetMainScroll(scrollView: ScrollView | null): void {
   scrollView.scrollTo({ y: 0, animated: false });
 }
 
+/** The approved mockup's exact copy shape: `"⚠ DS Viewer <version> is available — includes
+ *  breaking changes · Migration guide · Review update"`, dismissible with an `×` labeled "Dismiss
+ *  for <version>". The release's own GitHub page stands in for a dedicated migration-guide URL,
+ *  which this plan's design text does not otherwise name.
+ *
+ *  Important finding, Fable correction pass: both links now carry a real `href` — `role="link"`
+ *  with only `onPress` (as `CatalogSidebar.tsx`'s own finding already documents) never activates on
+ *  Enter under react-native-web unless the element is a genuine anchor. `role="status"` (not
+ *  `"alert"`, the mockup's own choice) — a non-urgent notice should not interrupt assistive tech. */
+function MajorBanner({ update, onReviewUpdate, onDismiss }: { update: UpdateNotice; onReviewUpdate: () => void; onDismiss: () => void }) {
+  const releaseUrl = `https://github.com/krapwoo/design-system-viewer/releases/tag/v${update.latest}`;
+  return (
+    <View style={bannerStyles.banner} role="status">
+      <Text style={bannerStyles.text}>
+        {'⚠ '}
+        <Text style={bannerStyles.bold}>{`DS Viewer ${update.latest} is available`}</Text>
+        {' — includes breaking changes · '}
+        <Text
+          role="link"
+          style={bannerStyles.link}
+          {...({ href: releaseUrl, hrefAttrs: { target: '_blank', rel: 'noopener noreferrer' } } as Record<string, unknown>)}
+        >
+          Migration guide
+        </Text>
+        {' · '}
+        <Text role="link" style={bannerStyles.link} onPress={onReviewUpdate} {...({ href: hashForId(UPDATE_PAGE_ID) } as Record<string, unknown>)}>
+          Review update
+        </Text>
+      </Text>
+      <Pressable onPress={onDismiss} accessibilityRole="button" accessibilityLabel={`Dismiss for ${update.latest}`} style={bannerStyles.close}>
+        <Text style={bannerStyles.closeGlyph}>×</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+const bannerStyles = StyleSheet.create({
+  banner: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: CATALOG_SPACE.md,
+    backgroundColor: CATALOG_COLOR.warningSubtle,
+    borderWidth: 1,
+    borderColor: CATALOG_COLOR.warningBorder,
+    borderRadius: CATALOG_RADIUS.md,
+    paddingVertical: 10,
+    paddingHorizontal: 14,
+    marginBottom: 18,
+  },
+  text: { flex: 1, fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.warning },
+  bold: { fontWeight: '700' },
+  link: { color: CATALOG_COLOR.warning, fontWeight: '700', textDecorationLine: 'underline' },
+  close: { width: 32, height: 32, borderRadius: CATALOG_RADIUS.sm, alignItems: 'center', justifyContent: 'center' },
+  closeGlyph: { fontSize: 18, color: CATALOG_COLOR.warning },
+});
+
 /**
  * The whole catalog: a persistent, searchable sidebar plus ONE selected page. Selecting a page
  * replaces the main content (no long scrolling document, no scroll-spy). On web the page lives in
@@ -49,6 +110,8 @@ export function CatalogShell<TId extends string>({
   groups,
   sections,
   defaultPreviewWidths,
+  update,
+  updateEndpoint,
 }: {
   /** Short product/app name — the sidebar logo and the breadcrumb root. */
   appName: string;
@@ -62,11 +125,20 @@ export function CatalogShell<TId extends string>({
   /** Preview widths for component pages without their own `previewWidths`. Default: `[402]`
    *  (phone width). Pass 'full' for a catalog whose previews are not phone components. */
   defaultPreviewWidths?: PreviewWidths;
+  /** Design §5's update notice — `null`/`undefined` when no update is known (disabled, offline,
+   *  or already up to date; the viewer treats all three identically: no footer, no banner, no
+   *  update page content). */
+  update?: UpdateNotice | null;
+  /** The local endpoint's base URL and per-run secret — `dev` generates both (Task 18) and
+   *  `writeWorkspace`'s generated entry file bakes them in (Task 17). Absent in a build that
+   *  disables the endpoint entirely — `UpdatePanel` degrades to showing the plan/notice with no
+   *  **Update now** button when this is missing. */
+  updateEndpoint?: { baseUrl: string; secret: string };
 }) {
   const sectionsById = useMemo(() => new Map(sections.map((def) => [def.id, def])), [sections]);
   const order = useMemo(() => orderedIds(groups, new Set(sectionsById.keys())), [groups, sectionsById]);
-  const [active, setActive] = useState<TId | undefined>(() =>
-    isWeb() ? idFromHash(window.location.hash, order) : order[0],
+  const [active, setActive] = useState<ShellPageId<TId> | undefined>(() =>
+    isWeb() ? resolveActiveFromHash(window.location.hash, order) : order[0],
   );
 
   const scrollRef = useRef<ScrollView>(null);
@@ -76,7 +148,7 @@ export function CatalogShell<TId extends string>({
   const pushHistoryNext = useRef(false);
   const focusHeadingNext = useRef(false);
 
-  const select = useCallback((id: TId) => {
+  const select = useCallback((id: ShellPageId<TId>) => {
     if (id === activeRef.current) {
       focusElement(headingRef.current);
       return;
@@ -90,7 +162,7 @@ export function CatalogShell<TId extends string>({
   useEffect(() => {
     if (!isWeb()) return;
     const onHashChange = () => {
-      const id = idFromHash(window.location.hash, order);
+      const id = resolveActiveFromHash(window.location.hash, order);
       if (id === undefined) return;
       if (id !== activeRef.current) {
         focusHeadingNext.current = true;
@@ -123,18 +195,40 @@ export function CatalogShell<TId extends string>({
     if (focus) focusElement(headingRef.current);
   }, [active]);
 
-  const activeDef = active !== undefined ? sectionsById.get(active) : undefined;
+  const activeDef = active !== undefined && active !== UPDATE_PAGE_ID ? sectionsById.get(active) : undefined;
+
+  const [dismissedMajor, setDismissedMajor] = useState<string | null>(() =>
+    isWeb() ? window.localStorage.getItem('ds-viewer-dismissed-major') : null,
+  );
+  const dismissMajorBanner = useCallback(() => {
+    if (!update) return;
+    if (isWeb()) window.localStorage.setItem('ds-viewer-dismissed-major', update.latest);
+    setDismissedMajor(update.latest);
+  }, [update]);
+  const footer = footerLabel(update)
+    ? { label: footerLabel(update)!, active: active === UPDATE_PAGE_ID, onPress: () => select(UPDATE_PAGE_ID) }
+    : undefined;
+  // Design: the banner shows on every *normal* page; once you're already looking at the update
+  // page there is nothing left for "Review update" to do, so it's hidden there (confirmed against
+  // the approved mockup's own `frame()`: the banner only ever renders when `!isPanel`).
+  const showBanner = active !== UPDATE_PAGE_ID && shouldShowMajorBanner(update, dismissedMajor);
 
   return (
     <View style={styles.root}>
-      <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} active={active} onPress={select} />
+      <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} active={active} onPress={select} footer={footer} />
       <ScrollView ref={scrollRef} style={styles.main} contentContainerStyle={styles.mainContent}>
-        {activeDef ? (
+        {active === UPDATE_PAGE_ID ? (
+          <UpdatePanel update={update ?? null} endpoint={updateEndpoint} appName={appName} headingRef={headingRef} />
+        ) : activeDef ? (
           <SectionBlock
             key={activeDef.id}
             def={activeDef}
             groupLabel={groupLabelFor(groups, activeDef.id)}
             breadcrumbRoot={appName}
+            // The approved mockup's own `PAGE_BG` order: crumb, then banner, then title — the
+            // banner used to render above the breadcrumb instead (Important finding, Fable
+            // correction pass).
+            banner={showBanner && update ? <MajorBanner update={update} onReviewUpdate={() => select(UPDATE_PAGE_ID)} onDismiss={dismissMajorBanner} /> : undefined}
             pager={{
               previousId: neighbors(order, activeDef.id).previous,
               nextId: neighbors(order, activeDef.id).next,

package/native/catalog/CatalogSidebar.tsx

@@ -3,7 +3,7 @@ import { View, Text, ScrollView, Pressable, StyleSheet, Image } from 'react-nati
 import type { ImageSourcePropType, LayoutChangeEvent, NativeSyntheticEvent, ImageLoadEventData } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { logoLayout } from './logoLayout';
-import { filterGroups, hashForId } from './catalogNavigation';
+import { filterGroups, hashForId, UPDATE_PAGE_ID } from './catalogNavigation';
 import type { NavGroup } from './types';
 import { CatalogSearchInput } from './CatalogSearchInput';
 
@@ -43,6 +43,32 @@ function NavItem<TId extends string>({ id, active, onPress }: { id: TId; active:
   );
 }
 
+function FooterLink({ label, active, onPress }: { label: string; active: boolean; onPress: () => void }) {
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  return (
+    <Pressable
+      onPress={onPress}
+      onHoverIn={() => setHovered(true)}
+      onHoverOut={() => setHovered(false)}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      accessibilityRole="link"
+      accessibilityState={{ selected: active }}
+      {...({ href: hashForId(UPDATE_PAGE_ID), ...(active ? { 'aria-current': 'page' } : null) } as Record<string, unknown>)}
+      style={({ pressed }) => [
+        styles.footerLink,
+        (pressed || hovered) && styles.footerLinkHover,
+        active && styles.footerLinkActive,
+        focused && styles.focusRing,
+      ]}
+    >
+      <View style={styles.footerDot} />
+      <Text style={[styles.footerLabel, active && styles.footerLabelActive]}>{label}</Text>
+    </Pressable>
+  );
+}
+
 /**
  * Catalog navigation: app name, caption, a filter field, and one link per page under grouped
  * headings. Selecting a link opens that page (CatalogShell owns which page is shown). The filter
@@ -55,6 +81,7 @@ export function CatalogSidebar<TId extends string>({
   groups,
   active,
   onPress,
+  footer,
 }: {
   logo: string;
   /** Optional logo image, validated and bundled by `cli/workspace.ts` from the project's `logo`
@@ -64,8 +91,12 @@ export function CatalogSidebar<TId extends string>({
   logoImageSource?: ImageSourcePropType;
   caption: string;
   groups: NavGroup<TId>[];
-  active: TId | undefined;
+  active: string | undefined;
   onPress: (id: TId) => void;
+  /** The quiet update-notice link below the nav list (design §5's footer line), or `undefined`
+   *  when there is no update to show. `active` is true while the update page itself is open — it
+   *  gets the same active styling a selected nav item would. */
+  footer?: { label: string; active: boolean; onPress: () => void };
 }) {
   const [query, setQuery] = useState('');
   // A bundled local image (the only kind `cli/workspace.ts` ever produces — see its doc comment
@@ -165,6 +196,11 @@ export function CatalogSidebar<TId extends string>({
           </View>
         ))}
       </ScrollView>
+      {footer && (
+        <View style={styles.footerContainer}>
+          <FooterLink label={footer.label} active={footer.active} onPress={footer.onPress} />
+        </View>
+      )}
     </View>
   );
 }
@@ -193,6 +229,26 @@ const styles = StyleSheet.create({
   inlineHeaderTop: { alignItems: 'flex-start' },
   inlineText: { flex: 1, minWidth: 0 },
   empty: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, paddingHorizontal: CATALOG_LAYOUT.navItemPaddingX, paddingVertical: 8 },
+  footerContainer: {
+    borderTopWidth: 1,
+    borderTopColor: CATALOG_COLOR.borderHairline,
+    paddingHorizontal: CATALOG_LAYOUT.sidebarPaddingX,
+    paddingTop: 10,
+    paddingBottom: 14,
+  },
+  footerLink: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: CATALOG_SPACE.sm,
+    minHeight: CATALOG_LAYOUT.controlSize,
+    paddingHorizontal: 10,
+    borderRadius: CATALOG_RADIUS.sm,
+  },
+  footerLinkHover: { backgroundColor: CATALOG_COLOR.surfacePressed },
+  footerLinkActive: { backgroundColor: CATALOG_COLOR.accentSubtle },
+  footerDot: { width: 8, height: 8, borderRadius: 4, backgroundColor: CATALOG_COLOR.accent, flexShrink: 0 },
+  footerLabel: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  footerLabelActive: { color: CATALOG_COLOR.accent, fontWeight: '700' },
   groupLabel: {
     fontSize: CATALOG_TYPE.xs,
     fontWeight: '800',

package/native/catalog/SectionBlock.tsx

@@ -213,6 +213,7 @@ export function SectionBlock<TId extends string>({
   def,
   groupLabel,
   breadcrumbRoot,
+  banner,
   pager,
   headingRef,
   headingLevel = 1,
@@ -221,6 +222,9 @@ export function SectionBlock<TId extends string>({
   def: SectionDef<TId>;
   groupLabel?: string;
   breadcrumbRoot?: string;
+  /** The major-update banner (`CatalogShell`'s own `MajorBanner`), rendered between the breadcrumb
+   *  and the title — the approved mockup's own `PAGE_BG` order: crumb, then banner, then title. */
+  banner?: React.ReactNode;
   pager?: SectionPager<TId>;
   headingRef?: React.Ref<View>;
   headingLevel?: 1 | 2;
@@ -238,6 +242,7 @@ export function SectionBlock<TId extends string>({
       {groupLabel && (
         <Text style={styles.breadcrumb}>{breadcrumbRoot ? `${breadcrumbRoot} / ${groupLabel}` : groupLabel}</Text>
       )}
+      {banner}
       <View style={styles.titlebar}>
         <View style={styles.titleText}>
           {/* The focus target is the heading itself, so assistive tech announces its role and level. */}