@igstack/app-catalog-frontend-core 3.0.0 → 4.0.0-alpha-20260919004140

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igstack/app-catalog-frontend-core",
-  "version": "3.0.0",
+  "version": "4.0.0-alpha-20260919004140",
   "description": "Frontend core library for App Catalog",
   "homepage": "https://github.com/lislon/app-catalog",
   "repository": {
@@ -113,7 +113,7 @@
     "tailwindcss": "^4.1.7",
     "tiptap-markdown": "^0.8.0",
     "tslib": "^2.3.0",
-    "@igstack/app-catalog-shared-core": "3.0.0"
+    "@igstack/app-catalog-shared-core": "4.0.0-alpha-20260919004140"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.0.5",
@@ -140,7 +140,7 @@
     "vite-plugin-static-copy": "^3.1.4",
     "vite-plugin-svgr": "^4.2.0",
     "vitest": "^4.1.2",
-    "@igstack/app-catalog-backend-core": "3.0.0"
+    "@igstack/app-catalog-backend-core": "4.0.0-alpha-20260919004140"
   },
   "peerDependencies": {
     "react": "19.1.2",
@@ -149,7 +149,7 @@
     "vite": "^6.3.5",
     "vite-plugin-svgr": "^4.2.0"
   },
-  "gitHead": "9762dd89f7623b15f0507f9936308720b58527ab",
+  "gitHead": "34a5c6bcfd90191f91c4bb520787aa126559e293",
   "scripts": {
     "build": "vite build",
     "build:lenient": "vite build --mode lenient",

package/src/__tests__/modules/appCatalog/utils/areaGrouping.test.ts

@@ -5,6 +5,7 @@ import type {
 } from '@igstack/app-catalog-backend-core'
 import {
   DAY_TO_DAY_AREA_KEY,
+  DAY_TO_DAY_TAG,
   areaLabel,
   categoryOf,
   groupByArea,
@@ -37,21 +38,32 @@ describe('groupByArea', () => {
       app('f1', ['category:finance']),
       app('s1', ['category:security']),
       app('f2', ['category:finance']),
-      app('everyone', ['category:security', 'universality:everyone']),
+      app('shelved', ['category:security', DAY_TO_DAY_TAG]),
     ])
     expect(groups.map(([key, list]) => [key, list.length])).toEqual([
       [DAY_TO_DAY_AREA_KEY, 1],
       ['finance', 2],
-      ['security', 1],
+      ['security', 2],
     ])
   })
 
-  it('folds a configured category into the day-to-day group', () => {
-    const groups = groupByArea(
-      [app('lunch', ['category:perks']), app('bank', ['category:finance'])],
-      ['perks'],
+  it('keeps a shelved app in its own category too', () => {
+    const groups = groupByArea([
+      app('chat', ['category:finance', DAY_TO_DAY_TAG]),
+    ])
+    expect(groups.map(([key, list]) => [key, list.map((a) => a.slug)])).toEqual(
+      [
+        [DAY_TO_DAY_AREA_KEY, ['chat']],
+        ['finance', ['chat']],
+      ],
     )
-    expect(groups.map(([key]) => key)).toEqual([DAY_TO_DAY_AREA_KEY, 'finance'])
+  })
+
+  it('ignores a reach facet — only the placement tag shelves an app', () => {
+    const groups = groupByArea([
+      app('popular', ['category:finance', 'universality:everyone']),
+    ])
+    expect(groups.map(([key]) => key)).toEqual(['finance'])
   })
 
   it('omits the day-to-day group when nothing belongs there', () => {

package/src/__tests__/modules/appCatalog/utils/quickJump.test.ts

@@ -0,0 +1,84 @@
+import type { QuickJump, Resource } from '@igstack/app-catalog-backend-core'
+import { describe, expect, it } from 'vitest'
+
+import {
+  buildQuickJumpUrl,
+  groupQuickJumps,
+  quickJumpFieldName,
+} from '~/modules/appCatalog/utils/quickJump'
+
+const onHost: QuickJump = {
+  identity: 'Case Id',
+  title: 'View case',
+  url: '{{baseHost}}/app/case?id={{value}}',
+}
+const absolute: QuickJump = {
+  identity: 'Case Id',
+  title: 'Search the event log',
+  url: 'https://events.example.com/search?q={{value}}',
+}
+
+function resource(quickJumps: QuickJump[], appUrl?: string): Resource {
+  return {
+    id: 'r1',
+    slug: 'app',
+    displayName: 'App',
+    description: '',
+    appUrl,
+    quickJumps,
+  }
+}
+
+describe('buildQuickJumpUrl', () => {
+  it("substitutes the resource's own host, without its trailing slash", () => {
+    expect(buildQuickJumpUrl(onHost, '42', 'https://app.example.com/')).toBe(
+      'https://app.example.com/app/case?id=42',
+    )
+  })
+
+  it('drops a jump that needs a host the resource does not have', () => {
+    expect(buildQuickJumpUrl(onHost, '42', undefined)).toBeNull()
+    expect(buildQuickJumpUrl(absolute, '42', undefined)).toBe(
+      'https://events.example.com/search?q=42',
+    )
+  })
+
+  it('encodes the typed value exactly once', () => {
+    // env-hopper ships %2540 in places — a genuine double-encode bug.
+    expect(buildQuickJumpUrl(absolute, 'a b&c@d')).toBe(
+      'https://events.example.com/search?q=a%20b%26c%40d',
+    )
+  })
+
+  it('trims the typed value', () => {
+    expect(buildQuickJumpUrl(absolute, '  42\n')).toBe(
+      'https://events.example.com/search?q=42',
+    )
+  })
+})
+
+describe('groupQuickJumps', () => {
+  it('groups by identity in first-appearance order and drops unbuildable jumps', () => {
+    const app = resource([
+      absolute,
+      { ...onHost, identity: 'Clinic Id' },
+      { ...absolute, title: 'Second case link' },
+    ])
+
+    expect(groupQuickJumps(app)).toEqual([
+      {
+        identity: 'Case Id',
+        jumps: [absolute, { ...absolute, title: 'Second case link' }],
+      },
+    ])
+  })
+})
+
+describe('quickJumpFieldName', () => {
+  it('derives one stable autofill key per identity label', () => {
+    expect(quickJumpFieldName('Case Id')).toBe('qj-case-id')
+    expect(quickJumpFieldName('Sequencing Sample Id')).toBe(
+      'qj-sequencing-sample-id',
+    )
+  })
+})

package/src/index.tsx

@@ -2,6 +2,9 @@ export { appPropsFactory } from './appPropsFactory.js'
 export { App } from './App'
 export type { AppProps } from './App'
 export type { AreaIcon, AreasSettings, UiSettings } from './types/uiSettings'
-export { DAY_TO_DAY_AREA_KEY } from './modules/appCatalog/utils/areaGrouping'
+export {
+  DAY_TO_DAY_AREA_KEY,
+  DAY_TO_DAY_TAG,
+} from './modules/appCatalog/utils/areaGrouping'
 export { PwaAutoUpdateProvider, usePwaAutoUpdate } from './modules/pwa'
 export type { PwaAutoUpdateOptions, PwaUpdateHandle } from './modules/pwa'

package/src/modules/appCatalog/ui/catalog/AppCatalogGrid.tsx

@@ -660,10 +660,7 @@ export function AppCatalogGrid({
 
   // Grouped: day-to-day tools first, then areas biggest-first so the page opens
   // on the areas most people need. Within an area, alpha (from browse).
-  const browseGroups = useMemo(
-    () => groupByArea(browse, areas?.dayToDayCategories),
-    [browse, areas?.dayToDayCategories],
-  )
+  const browseGroups = useMemo(() => groupByArea(browse), [browse])
 
   const isSearching = searchValue.trim() !== ''
   const searchRef = useRef<HTMLInputElement>(null)

package/src/modules/appCatalog/ui/components/QuickJumpSection.tsx

@@ -0,0 +1,253 @@
+import type { QuickJump, Resource } from '@igstack/app-catalog-backend-core'
+import { Pin, Rabbit, Settings2 } from 'lucide-react'
+import React from 'react'
+
+import { cn } from '~/lib/utils'
+import { Checkbox } from '~/ui/checkbox'
+import { Input } from '~/ui/input'
+import { Popover, PopoverContent, PopoverTrigger } from '~/ui/popover'
+import {
+  buildQuickJumpUrl,
+  groupQuickJumps,
+  quickJumpFieldName,
+} from '~/modules/appCatalog/utils/quickJump'
+
+/**
+ * Per-user, per-app preferences. Which identities to render and whether to hoist
+ * the section to the top of the card — a browser-local display choice, so it
+ * lives in localStorage rather than costing a table and an authenticated route.
+ */
+interface QuickJumpPrefs {
+  /** Keep the section at the top of the app card. */
+  pinned?: boolean
+  /** Identity labels to render. Absent = the first identity only. */
+  shown?: string[]
+}
+
+function prefsKey(slug: string) {
+  return `ac:quickjump:${slug}`
+}
+
+function readPrefs(slug: string): QuickJumpPrefs {
+  try {
+    const raw = localStorage.getItem(prefsKey(slug))
+    return raw ? (JSON.parse(raw) as QuickJumpPrefs) : {}
+  } catch {
+    return {}
+  }
+}
+
+function writePrefs(slug: string, prefs: QuickJumpPrefs) {
+  try {
+    localStorage.setItem(prefsKey(slug), JSON.stringify(prefs))
+  } catch {
+    // Private mode / full quota: the session still works, just doesn't persist.
+  }
+}
+
+/**
+ * One jump button. Disabled until its identity has a value: greyed and dashed,
+ * so the empty input above reads as the thing to do first. The green JUMP tell
+ * only shows on hover — one per row is repetition, not signal.
+ */
+function JumpButton({
+  jump,
+  value,
+  appUrl,
+}: {
+  jump: QuickJump
+  value: string
+  appUrl?: string
+}) {
+  const trimmed = value.trim()
+  const href = trimmed ? buildQuickJumpUrl(jump, trimmed, appUrl) : null
+
+  return (
+    <a
+      href={href ?? undefined}
+      target="_blank"
+      rel="noopener noreferrer"
+      aria-disabled={href ? undefined : true}
+      title={href ?? `Fill in ${jump.identity} first`}
+      className={cn(
+        'group/jump flex items-center gap-2 rounded-md border px-2.5 py-1.5 text-left text-xs font-semibold transition-colors',
+        href
+          ? 'animate-button-pop bg-card shadow-sm hover:bg-accent/40'
+          : 'pointer-events-none border-dashed bg-muted text-muted-foreground opacity-70',
+      )}
+    >
+      <span className="min-w-0 flex-1 wrap-anywhere">
+        {jump.title}
+        {trimmed && <span className="ml-1 font-mono">{trimmed}</span>}
+      </span>
+      <span
+        className={cn(
+          'flex shrink-0 origin-bottom items-center gap-1 text-hopper opacity-0 transition-[opacity,transform]',
+          'group-hover/jump:-translate-x-0.5 group-hover/jump:translate-y-0.5 group-hover/jump:rotate-2 group-hover/jump:scale-y-90',
+          'group-hover/jump:opacity-100 group-focus-visible/jump:opacity-100 motion-reduce:transform-none',
+        )}
+      >
+        <span className="text-[0.65rem] font-extrabold tracking-widest">
+          JUMP
+        </span>
+        <Rabbit className="size-4" />
+      </span>
+    </a>
+  )
+}
+
+/**
+ * Quick Jump: paste an id, open the matching page. One column per identity the
+ * app's jumps ask for; only the identities the user keeps are rendered, the rest
+ * are one click away behind Configure.
+ */
+export function QuickJumpSection({ app }: { app: Resource }) {
+  const identities = React.useMemo(() => groupQuickJumps(app), [app])
+  const [prefs, setPrefs] = React.useState<QuickJumpPrefs>(() =>
+    readPrefs(app.slug),
+  )
+  const [values, setValues] = React.useState<Record<string, string>>({})
+
+  // Re-read when the panel moves to another app — one key per slug.
+  React.useEffect(() => {
+    setPrefs(readPrefs(app.slug))
+    setValues({})
+  }, [app.slug])
+
+  if (identities.length === 0) return null
+
+  const savePrefs = (next: QuickJumpPrefs) => {
+    setPrefs(next)
+    writePrefs(app.slug, next)
+  }
+
+  const shown = prefs.shown ?? identities.slice(0, 1).map((i) => i.identity)
+  const visible = identities.filter((i) => shown.includes(i.identity))
+
+  const toggleShown = (identity: string) =>
+    savePrefs({
+      ...prefs,
+      shown: shown.includes(identity)
+        ? shown.filter((s) => s !== identity)
+        : [...shown, identity],
+    })
+
+  return (
+    <div className={cn('mt-6', prefs.pinned && 'order-[-1]')}>
+      <div className="mb-2 flex items-center gap-2">
+        <Rabbit className="size-4 shrink-0 text-hopper" />
+        <h3 className="text-sm font-medium">Quick Jump</h3>
+        <button
+          type="button"
+          onClick={() => savePrefs({ ...prefs, pinned: !prefs.pinned })}
+          title={
+            prefs.pinned
+              ? 'Unpin section'
+              : 'Pin section — keep Quick Jump at the top of this card'
+          }
+          aria-pressed={prefs.pinned ?? false}
+          className={cn(
+            'rounded-sm p-0.5 transition-opacity hover:bg-muted',
+            prefs.pinned
+              ? 'text-primary'
+              : 'text-muted-foreground opacity-50 hover:opacity-100',
+          )}
+        >
+          <Pin className="size-3.5" />
+        </button>
+        {prefs.pinned && (
+          <span className="text-xs font-semibold text-primary">
+            pinned to top
+          </span>
+        )}
+
+        {/* Nothing to configure with a single identity. */}
+        {identities.length > 1 && (
+          <Popover>
+            <PopoverTrigger className="ml-auto inline-flex items-center gap-1.5 rounded-full border border-primary/45 bg-accent/45 px-2.5 py-1 text-xs font-bold shadow-sm transition-colors hover:border-primary hover:bg-accent/80">
+              <Settings2 className="size-3.5 text-primary" />
+              Configure ({visible.length}/{identities.length})
+            </PopoverTrigger>
+            <PopoverContent align="end" className="w-64 p-1.5">
+              <p className="px-1.5 pt-0.5 pb-1.5 text-[0.7rem] text-muted-foreground">
+                Tick an ID to show it on this card.
+              </p>
+              {identities.map(({ identity, jumps }) => (
+                <label
+                  key={identity}
+                  className="flex cursor-pointer items-center gap-2 rounded-sm px-1.5 py-1.5 text-sm hover:bg-muted"
+                >
+                  <Checkbox
+                    checked={shown.includes(identity)}
+                    onCheckedChange={() => toggleShown(identity)}
+                  />
+                  {identity}
+                  <span className="ml-auto font-mono text-[0.7rem] text-muted-foreground">
+                    {jumps.length}
+                  </span>
+                </label>
+              ))}
+            </PopoverContent>
+          </Popover>
+        )}
+      </div>
+      <p className="mb-3 text-xs text-muted-foreground">
+        Paste an ID and open the matching page.
+      </p>
+
+      {visible.length === 0 ? (
+        <p className="text-xs text-muted-foreground">
+          No IDs shown — pick one under Configure.
+        </p>
+      ) : (
+        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {visible.map(({ identity, jumps }) => {
+            const value = values[identity] ?? ''
+            return (
+              <div key={identity} className="flex min-w-0 flex-col gap-2">
+                <label
+                  className="truncate text-xs font-bold"
+                  htmlFor={`qj-${app.slug}-${identity}`}
+                >
+                  {identity}
+                </label>
+                <Input
+                  id={`qj-${app.slug}-${identity}`}
+                  // Namespaced per identity: the browser remembers values typed
+                  // for this identifier and offers them on every app using it.
+                  name={quickJumpFieldName(identity)}
+                  autoComplete="on"
+                  placeholder={identity}
+                  className="bg-card font-mono"
+                  value={value}
+                  onChange={(e) =>
+                    setValues((v) => ({ ...v, [identity]: e.target.value }))
+                  }
+                  onKeyDown={(e) => {
+                    const first = jumps[0]
+                    if (e.key !== 'Enter' || !first) return
+                    if (!e.currentTarget.value.trim()) return
+                    const url = buildQuickJumpUrl(
+                      first,
+                      e.currentTarget.value,
+                      app.appUrl,
+                    )
+                    if (url) window.open(url, '_blank', 'noopener,noreferrer')
+                  }}
+                />
+                {jumps.map((jump) => (
+                  <JumpButton
+                    key={`${jump.title}:${jump.url}`}
+                    jump={jump}
+                    value={value}
+                    appUrl={app.appUrl}
+                  />
+                ))}
+              </div>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/modules/appCatalog/ui/detail/AppDetails.tsx

@@ -20,6 +20,7 @@ import {
 } from '~/ui/accordion'
 import { AccessRequestSection } from '../components/AccessRequestSection'
 import { AccessPrerequisiteChain } from '../components/AccessPrerequisiteChain'
+import { QuickJumpSection } from '../components/QuickJumpSection'
 import { useAppCatalogFilters } from '../context/AppCatalogFiltersContext'
 import { PersonBadge } from '../components/PersonBadge'
 import { useUser } from '~/modules/auth'
@@ -215,8 +216,9 @@ export function AppDetails({
   return (
     <>
       <div className="flex h-full flex-col p-6">
-        {/* Icon and Title */}
-        <div className="border-b pb-6">
+        {/* Icon and Title — always first: a pinned Quick Jump takes order -1,
+            so the header claims -2 rather than being pushed below it. */}
+        <div className="-order-2 border-b pb-6">
           <div className="flex items-center gap-3">
             <AppIcon app={app} className="size-16" />
             <div className="-mx-3 flex-1 min-w-0">
@@ -352,6 +354,10 @@ export function AppDetails({
         {/* Access Request Section — hero of the detail, shown before description */}
         <AccessRequestSection app={app} approvalMethods={approvalMethods} />
 
+        {/* Quick Jump — paste an id, open the matching page. Hoists itself to
+            the top of the card (flex order) when the user pins it. */}
+        <QuickJumpSection app={app} />
+
         {/* Description */}
         <div className="mt-6">
           <h3 className="mb-2 text-sm font-medium">Description</h3>

package/src/modules/appCatalog/utils/areaGrouping.ts

@@ -6,14 +6,20 @@ import type {
 /**
  * Grouping of the full resource list into areas.
  *
- * The vocabulary itself is NOT here: which `category:<value>` tags exist, what
- * they are called and which of them belong on the day-to-day shelf is
- * deployment-specific. Labels come from the catalog's own tag definitions and
- * icons from `UiSettings.areas`, so the core only knows the mechanism.
+ * The vocabulary itself is NOT here: which `category:<value>` tags exist and
+ * what they are called is deployment-specific. Labels come from the catalog's
+ * own tag definitions and icons from `UiSettings.areas`, so the core only knows
+ * the mechanism.
  */
 
 const CATEGORY_PREFIX = 'category:'
-const EVERYONE_TAG = 'universality:everyone'
+
+/**
+ * Opt-in to the day-to-day shelf. Placement only — it says where a resource is
+ * surfaced, never what it is or how many people use it, so it is independent of
+ * both `category:` and any reach/audience facet the catalog may declare.
+ */
+export const DAY_TO_DAY_TAG = 'placement:day-to-day'
 
 /**
  * Synthetic key for the merged first group. Underscored so it cannot collide
@@ -38,23 +44,17 @@ const humanize = (key: string): string => {
  * Day-to-day tools first, then one area per category, biggest area first.
  * Input order is preserved inside each group.
  *
- * `dayToDayCategories` are categories that fold into the day-to-day group
- * instead of getting an area of their own (perks, office services, …).
+ * The shelf is **additive**: a `placement:day-to-day` resource is a shortcut at
+ * the top *and* still listed under its own category. Hoisting it out instead
+ * silently emptied categories of their best-known members.
  */
-export function groupByArea(
-  apps: Resource[],
-  dayToDayCategories: readonly string[] = [],
-): [string, Resource[]][] {
-  const folded = new Set(dayToDayCategories)
+export function groupByArea(apps: Resource[]): [string, Resource[]][] {
   const dayToDay: Resource[] = []
   const byCategory = new Map<string, Resource[]>()
 
   for (const app of apps) {
+    if (app.tags?.includes(DAY_TO_DAY_TAG)) dayToDay.push(app)
     const key = categoryOf(app)
-    if (app.tags?.includes(EVERYONE_TAG) || folded.has(key)) {
-      dayToDay.push(app)
-      continue
-    }
     const list = byCategory.get(key)
     if (list) list.push(app)
     else byCategory.set(key, [app])

package/src/modules/appCatalog/utils/quickJump.ts

@@ -0,0 +1,57 @@
+import type { QuickJump, Resource } from '@igstack/app-catalog-backend-core'
+
+/**
+ * Build a jump's target url. The whole template "engine": two placeholders,
+ * `{{baseHost}}` substituted raw (it is a url prefix) and `{{value}}` encoded
+ * exactly once. Returns null when the jump needs a host the resource does not
+ * have — the caller drops it instead of rendering a broken link.
+ */
+export function buildQuickJumpUrl(
+  jump: QuickJump,
+  value: string,
+  appUrl?: string,
+): string | null {
+  const needsHost = jump.url.includes('{{baseHost}}')
+  const host = (appUrl ?? '').replace(/\/+$/, '')
+  if (needsHost && !host) return null
+
+  return jump.url
+    .replaceAll('{{baseHost}}', host)
+    .replaceAll('{{value}}', encodeURIComponent(value.trim()))
+}
+
+export interface QuickJumpIdentity {
+  /** Human label, e.g. "Case Id" — also the column heading. */
+  identity: string
+  jumps: QuickJump[]
+}
+
+/**
+ * Group an app's jumps by identity, keeping first-appearance order (so company
+ * config controls the column order) and dropping jumps this app cannot build.
+ */
+export function groupQuickJumps(app: Resource): QuickJumpIdentity[] {
+  const groups: QuickJumpIdentity[] = []
+
+  for (const jump of app.quickJumps ?? []) {
+    if (buildQuickJumpUrl(jump, 'probe', app.appUrl) === null) continue
+
+    const group = groups.find((g) => g.identity === jump.identity)
+    if (group) group.jumps.push(jump)
+    else groups.push({ identity: jump.identity, jumps: [jump] })
+  }
+
+  return groups
+}
+
+/**
+ * Autofill key for an identity's input. Namespaced and derived from the label,
+ * so the same identifier autofills from history across apps — the browser gives
+ * us per-identity value history for free.
+ */
+export function quickJumpFieldName(identity: string): string {
+  return `qj-${identity
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')}`
+}

package/src/types/uiSettings.ts

@@ -19,11 +19,6 @@ export interface AreasSettings {
    * merged first group. Areas without an icon render title-only.
    */
   icons?: Record<string, AreaIcon>
-  /**
-   * Category values that fold into the day-to-day group instead of getting an
-   * area of their own (e.g. perks, office services).
-   */
-  dayToDayCategories?: string[]
   /** Title of the merged first group. Defaults to "Day-to-day tools". */
   dayToDayLabel?: string
 }