@igstack/app-catalog-frontend-core 6.8.4 → 6.10.0

package/src/modules/appCatalog/ui/detail/communityDraft.ts

@@ -0,0 +1,80 @@
+/**
+ * Where a half-written note lives while it is not sent.
+ *
+ * The input sits inside a tab panel, and a panel unmounts while its tab is not
+ * the active one — so component state alone loses whatever someone typed or
+ * attached the moment they look at another tab. Losing someone's words is the
+ * one failure this feature cannot afford: reporting has to cost almost nothing,
+ * and "I typed it and it vanished" is how a person learns not to bother.
+ *
+ * Session rather than local storage: a draft is in-flight work, not a
+ * preference. Keyed by slug so two entries do not share one draft. Storage can
+ * throw outright in a locked-down context; a lost draft is not worth taking the
+ * card down over, so every access swallows that.
+ */
+
+/** One already-uploaded image waiting to be sent with the words. */
+export interface PendingImage {
+  id: string
+  name: string
+}
+
+const draftKey = (slug: string) => `ac.feedback.draft.${slug}`
+const imagesKey = (slug: string) => `ac.feedback.images.${slug}`
+
+export function readDraft(slug: string): string {
+  try {
+    return sessionStorage.getItem(draftKey(slug)) ?? ''
+  } catch {
+    return ''
+  }
+}
+
+export function writeDraft(slug: string, value: string): void {
+  try {
+    if (value) sessionStorage.setItem(draftKey(slug), value)
+    else sessionStorage.removeItem(draftKey(slug))
+  } catch {
+    /* see the module comment */
+  }
+}
+
+/**
+ * Images upload the moment they are picked, so the draft holds ids rather than
+ * files. Dropping an id here does NOT delete the image; the server sweeps
+ * whatever is never sent, which keeps "remove" instant.
+ */
+export function readAttachments(slug: string): PendingImage[] {
+  try {
+    const raw = sessionStorage.getItem(imagesKey(slug))
+    if (!raw) return []
+    const parsed: unknown = JSON.parse(raw)
+    if (!Array.isArray(parsed)) return []
+    return parsed.filter(
+      (entry): entry is PendingImage =>
+        typeof entry === 'object' &&
+        entry !== null &&
+        typeof (entry as PendingImage).id === 'string' &&
+        typeof (entry as PendingImage).name === 'string',
+    )
+  } catch {
+    return []
+  }
+}
+
+export function writeAttachments(slug: string, images: PendingImage[]): void {
+  try {
+    if (images.length > 0) {
+      sessionStorage.setItem(imagesKey(slug), JSON.stringify(images))
+    } else {
+      sessionStorage.removeItem(imagesKey(slug))
+    }
+  } catch {
+    /* see the module comment */
+  }
+}
+
+/** The stored image, at whatever size the browser lays it out. */
+export function attachmentUrl(id: string): string {
+  return `/api/feedback-attachments/${id}`
+}

package/src/modules/appCatalog/ui/detail/communityError.ts

@@ -0,0 +1,10 @@
+/**
+ * The server's reason when it gave a readable one ("Up to 3 images"), else a
+ * generic line. Validation failures arrive as serialized issue lists, which
+ * are not for a reader.
+ */
+export function formatCommunityError(error: unknown): string {
+  const reason =
+    error instanceof Error ? error.message.trim().replace(/\.$/, '') : ''
+  return reason && !/^[[{]/.test(reason) ? reason : 'Something went wrong'
+}

package/src/modules/appCatalog/ui/detail/composeComments.ts

@@ -0,0 +1,103 @@
+import type {
+  Claim,
+  FeedbackView as Note,
+} from '@igstack/app-catalog-backend-core'
+
+/** `pending` = still being checked; `used` = the card now relies on it. */
+export type CommentBadge = 'pending' | 'used' | null
+
+/** One row of the Comments feed. */
+export interface CommentEntry {
+  key: string
+  /** Null when a claim names no origin at all. */
+  who: string | null
+  /** Raw ISO date or instant, for the `title`. */
+  at: string
+  /** Null for a note sent without words; the feed says what it carried instead. */
+  text: string | null
+  badge: CommentBadge
+  /** The visitor's row, when the entry is one — what Edit, Dismiss and screenshots hang off. */
+  note?: Note
+}
+
+const FEEDBACK_ORIGIN = 'feedback:'
+
+function noteBadge(note: Note, linked: Claim[]): CommentBadge {
+  if (note.status === null) return 'pending'
+  if (linked.some((c) => c.status === 'review')) return 'pending'
+  if (note.status === 'acknowledged') return null
+  if (linked.some((c) => c.status === 'active')) return 'used'
+  return null
+}
+
+/** Who said a claim that has no note in the list. A URL reads as its host. */
+function claimWho(origin: string | undefined): string | null {
+  if (!origin) return null
+  if (origin.startsWith(FEEDBACK_ORIGIN)) return 'A visitor'
+  if (/^https?:\/\//.test(origin)) {
+    try {
+      return new URL(origin).host
+    } catch {
+      return origin
+    }
+  }
+  return origin
+}
+
+const time = (at: string) => Date.parse(at) || 0
+
+/**
+ * Everything said about an entry, one entry per visitor note, newest first.
+ *
+ * A claim whose origin is `feedback:<id>` belongs to that note: it sets the
+ * note's badge and is not shown again. A claim with no note in the list (its
+ * row is gone, or it came from a person, team or URL) stands on its own, in
+ * its own words. Archived claims are not shown.
+ */
+export function composeComments(
+  notes: Note[],
+  claims: Claim[],
+): CommentEntry[] {
+  const ids = new Set(notes.map((n) => n.id))
+  const byNote = new Map<string, Claim[]>()
+  const standalone: Claim[] = []
+  for (const claim of claims) {
+    if (claim.status === 'archived') continue
+    const id = claim.origin?.startsWith(FEEDBACK_ORIGIN)
+      ? claim.origin.slice(FEEDBACK_ORIGIN.length)
+      : null
+    if (id !== null && ids.has(id)) {
+      byNote.set(id, [...(byNote.get(id) ?? []), claim])
+    } else {
+      standalone.push(claim)
+    }
+  }
+  const entries: CommentEntry[] = [
+    ...notes.map(
+      (note): CommentEntry => ({
+        key: note.id,
+        who: note.authorName,
+        at: note.createdAt,
+        text: note.body,
+        badge: noteBadge(note, byNote.get(note.id) ?? []),
+        note,
+      }),
+    ),
+    ...standalone.map(
+      (claim, i): CommentEntry => ({
+        key: `claim-${i}`,
+        who: claimWho(claim.origin),
+        at: claim.addedAt,
+        text: claim.text,
+        badge: claim.status === 'active' ? 'used' : 'pending',
+      }),
+    ),
+  ]
+  return entries.sort((a, b) => time(b.at) - time(a.at))
+}
+
+/** The Behind this card count: exactly the feed's Pending badges. */
+export function countPending(notes: Note[], claims: Claim[]): number {
+  return composeComments(notes, claims).filter((e) => e.badge === 'pending')
+    .length
+}

package/src/modules/appCatalog/ui/detail/usePendingCount.ts

@@ -0,0 +1,26 @@
+import type { Claim } from '@igstack/app-catalog-backend-core'
+import { useQuery } from '@tanstack/react-query'
+import { useTRPC } from '~/api/infra/trpc'
+import { countPending } from './composeComments'
+
+const NO_CLAIMS: Claim[] = []
+
+/**
+ * How many entries in the Comments feed say Pending: open notes, notes whose
+ * claim is still in review, and review claims with no note of their own.
+ *
+ * The same query the feed runs, so the tab count and the feed share one cache
+ * entry and one request, and are composed by the same rules. Zero while
+ * loading or on error: until the notes arrive, a claim cannot be matched to
+ * its note, and a count that is not known yet is not shown.
+ */
+export function usePendingCount(
+  appSlug: string,
+  claims: Claim[] = NO_CLAIMS,
+): number {
+  const trpc = useTRPC()
+  const { data, error } = useQuery(
+    trpc.feedback.list.queryOptions({ resourceSlug: appSlug }),
+  )
+  return data || error ? countPending(data?.items ?? [], claims) : 0
+}

package/src/modules/extensions/features/resourceDetail.ts

@@ -38,7 +38,9 @@ export interface ResourceDetailSlots {
    * family has children (hundreds, in a large catalog) — keep the cell cheap and
    * defer anything expensive until it is interacted with. And the column only
    * appears when a plugin actually fills it, so a build with no plugin renders
-   * the table exactly as before.
+   * the table exactly as before. A plugin that serves only some parents says so
+   * in `appliesTo` (see `ResourceDetailSlotScopes`), so every other parent's
+   * table gets no column rather than a column of empty cells.
    */
   resourceSubResourceRowActions: {
     /** The child this row is showing. */
@@ -47,6 +49,46 @@ export interface ResourceDetailSlots {
     parent: Resource
     user: PluginUser | null
   }
+
+  /**
+   * "What happens next" line at the foot of the "How comments work" popover,
+   * beside the Comments heading on Behind this card.
+   *
+   * Tells the reader what becomes of the text they send. The OSS default is
+   * `Every note is reviewed. Facts that check out update the card and are
+   * marked Used as source.` A deployment with its own review loop substitutes
+   * its own text.
+   */
+  resourceDetailFeedbackNote: {
+    appSlug: string
+    appName: string
+  }
+
+  /**
+   * Where this card's own definition lives, at the foot of Behind this card.
+   *
+   * A quiet link such as "View this card's source". Only the deployment knows
+   * where its catalog entries are kept, so the core has no default and renders
+   * nothing here unless a plugin contributes.
+   */
+  resourceDetailCardSource: {
+    appSlug: string
+    appName: string
+  }
+}
+
+/**
+ * What the core knows when it decides a slot's LAYOUT, before any row renders.
+ *
+ * The input to a plugin's `appliesTo` predicate for that slot. A contribution
+ * renders as a component, so the core cannot ask it whether it would render
+ * nothing; the plugin has to say up front which scopes it serves.
+ */
+export interface ResourceDetailSlotScopes {
+  resourceSubResourceRowActions: {
+    /** The entry whose sub-resources table is being laid out. */
+    parent: Resource
+  }
 }
 
 /**
@@ -71,4 +113,6 @@ export const ResourceDetailAccessActions = mkSlot('resourceDetailAccessActions')
 export const ResourceSubResourceRowActions = mkSlot(
   'resourceSubResourceRowActions',
 )
+export const ResourceDetailFeedbackNote = mkSlot('resourceDetailFeedbackNote')
+export const ResourceDetailCardSource = mkSlot('resourceDetailCardSource')
 export const ResourceDetailProvider = mkWrapper('resourceDetailProvider')

package/src/modules/extensions/index.ts

@@ -5,6 +5,7 @@ import type { ReactNode } from 'react'
 // resolves it if it has mapped it, which the example app has not.
 import { useOptionalUser } from '../auth/AuthContext'
 import type {
+  ResourceDetailSlotScopes,
   ResourceDetailSlots,
   ResourceDetailWrappers,
 } from './features/resourceDetail'
@@ -20,9 +21,12 @@ export type { AssertDisjoint } from './types'
 export {
   ResourceDetailAccessActions,
   ResourceSubResourceRowActions,
+  ResourceDetailFeedbackNote,
+  ResourceDetailCardSource,
   ResourceDetailProvider,
 } from './features/resourceDetail'
 export type {
+  ResourceDetailSlotScopes,
   ResourceDetailSlots,
   ResourceDetailWrappers,
 } from './features/resourceDetail'
@@ -38,6 +42,9 @@ export type SlotSpec = ResourceDetailSlots
 /** Every wrapper slot in the core. */
 export type WrapperSpec = ResourceDetailWrappers
 
+/** The layout scope of every slot whose layout depends on more than presence. */
+export type SlotScopeSpec = ResourceDetailSlotScopes
+
 // Guard: with a second feature this becomes
 // `AssertDisjoint<ResourceDetailSlots, ServiceDeskSlots>` and fails with the
 // duplicated id spelled out in the error. With one feature it is trivially true,
@@ -63,6 +70,16 @@ export type PluginWrappers = {
   ) => ReactNode
 }
 
+/**
+ * Which layout scopes a plugin's slot contribution serves. Absent = all of them.
+ *
+ * Only slots listed in `SlotScopeSpec` take a predicate: those are the slots
+ * whose layout the core decides before rendering any contribution.
+ */
+export type PluginAppliesTo = {
+  [N in keyof SlotScopeSpec]?: (scope: SlotScopeSpec[N]) => boolean
+}
+
 /**
  * One deployment-specific feature's contribution to the core's UI.
  *
@@ -79,6 +96,7 @@ export interface AcPlugin {
   name: string
   slots?: PluginSlots
   wrappers?: PluginWrappers
+  appliesTo?: PluginAppliesTo
 }
 
 /**
@@ -93,9 +111,28 @@ export interface AcPlugin {
  * Use it ONLY for layout. A slot must never be the only route to something the
  * core itself needs, so branching behaviour on a plugin's presence is a design
  * smell even where branching layout is not.
+ *
+ * A slot in `SlotScopeSpec` also takes the scope being laid out, and counts only
+ * plugins whose `appliesTo` accepts it. An `undefined` scope means there is
+ * nothing to decide against, so the slot reads as unfilled.
  */
-export function useSlotFilled(slot: keyof SlotSpec): boolean {
-  return useExtensions().some((plugin) => Boolean(plugin.slots?.[slot]))
+export function useSlotFilled<TSlot extends keyof SlotSpec>(
+  slot: TSlot,
+  ...scope: TSlot extends keyof SlotScopeSpec
+    ? [scope: SlotScopeSpec[TSlot] | undefined]
+    : []
+): boolean {
+  const plugins = useExtensions()
+  const scoped = scope.length > 0
+  const value = scope[0]
+  if (scoped && value === undefined) return false
+  return plugins.some((plugin) => {
+    if (!plugin.slots?.[slot]) return false
+    const applies = plugin.appliesTo?.[slot] as
+      | ((s: typeof value) => boolean)
+      | undefined
+    return !scoped || !applies || applies(value)
+  })
 }
 
 /**

package/src/modules/extensions/types.ts

@@ -34,6 +34,7 @@ export interface PluginRegistration {
   name: string
   slots?: Record<string, OpaqueRenderer | undefined>
   wrappers?: Record<string, OpaqueRenderer | undefined>
+  appliesTo?: Record<string, ((scope: never) => boolean) | undefined>
 }
 
 /**

package/dist/esm/modules/appCatalog/ui/detail/FeedbackSection.d.ts

@@ -1,13 +0,0 @@
-export declare function FeedbackSection({ appSlug, 
-/**
- * Asked to open by the card's band, which is where the affordance now lives —
- * at the foot of this panel it was below the fold of a tab nobody opens unless
- * they already know what is in it.
- *
- * A count of how many times it has asked, so a second ask re-opens the composer
- * the first one closed on send. A boolean could not say "again".
- */
-openComposer, }: {
-    appSlug: string;
-    openComposer?: number;
-}): import("react/jsx-runtime").JSX.Element;