@asteby/metacore-runtime-react 23.7.1 → 23.9.0

package/src/index.ts

@@ -36,6 +36,7 @@ export {
     mergeLaneStages,
     resolveSmartLanes,
     smartLaneParams,
+    cardMatchesStageFilters,
     customStageFilterFields,
     isCustomStageDraftValid,
     slugifyStageKey,
@@ -44,6 +45,9 @@ export {
     CustomStageLaneMenu,
     CustomStageDialog,
     CustomStageDeleteDialog,
+    StageConditionBuilder,
+    StageConfigDialog,
+    stageFilterOpSymbol,
     SmartLane,
     CUSTOM_STAGE_COLORS,
     CUSTOM_STAGE_FILTER_OPS,
@@ -53,7 +57,21 @@ export {
     type CustomStageFilter,
     type CustomStageFilterOp,
     type UseCustomStagesResult,
+    type StageConfigTarget,
+    type StageConfigKind,
+    type StageConditionBuilderProps,
+    type StageConfigDialogProps,
 } from './custom-stages'
+export {
+    useStageLayout,
+    type StageLayout,
+    type UseStageLayoutResult,
+} from './stage-layout'
+export {
+    useStageOverrides,
+    type StageOverridePatch,
+    type UseStageOverridesResult,
+} from './stage-overrides'
 export {
     DynamicView,
     resolveViewRenderer,

package/src/stage-layout.ts

@@ -0,0 +1,93 @@
+// Stage layout — per-org persistence of the DynamicKanban lane order. Lets a
+// user drag the board's columns (declared stages, custom stages and smart
+// lanes alike) into any order; the chosen order is saved server-side and
+// re-applied on load (the ops backend stamps it onto `metadata.stages[].order`
+// / `smart_lanes[].order`, so the board already paints ordered — this hook only
+// owns the drag + the optimistic PUT).
+//
+// Non-intrusive by design: mirrors `useStageAutomations`. If the host wires no
+// `/stage-layout` endpoint, the GET 404s, `available` stays false, and the lane
+// drag simply never turns on — the kanban keeps working untouched.
+//
+// Contract (matches the ops backend; envelope is {success, data} → read .data):
+//   GET    /stage-layout?model=<m>  → { model, stage_order: string[] } | null
+//   PUT    /stage-layout            { model, stage_order: string[] }  (full order)
+//   DELETE /stage-layout?model=<m>  → reset to the declared order
+import { useCallback, useEffect, useState } from 'react'
+import { useApi } from './api-context'
+
+export interface StageLayout {
+    model: string
+    /** The full lane order — every lane key (stages + smart lanes) in order. */
+    stage_order: string[]
+}
+
+export interface UseStageLayoutResult {
+    /** True only after a successful GET — gates the lane drag + reset affordance. */
+    available: boolean
+    /** True when a custom order is stored server-side (drives the reset affordance). */
+    hasCustomLayout: boolean
+    /** Persist the full lane order (the new order of every lane key). Throws on failure. */
+    save: (order: string[]) => Promise<void>
+    /** Drop the stored order, reverting to the declared stage order. */
+    reset: () => Promise<void>
+}
+
+function unwrap(res: { data: any }): any {
+    const body = res?.data
+    if (body && typeof body === 'object' && 'data' in body) return body.data
+    return body
+}
+
+/**
+ * Loads a model's saved lane order (only to learn availability + whether a
+ * custom order exists) and exposes save/reset. A missing endpoint degrades to
+ * `available: false` so the board's lane drag stays off; a real save failure
+ * re-throws so the caller can revert its optimistic reorder.
+ */
+export function useStageLayout(model: string): UseStageLayoutResult {
+    const api = useApi()
+    const [available, setAvailable] = useState(false)
+    const [hasCustomLayout, setHasCustomLayout] = useState(false)
+
+    useEffect(() => {
+        let cancelled = false
+        api
+            .get(`/stage-layout?model=${encodeURIComponent(model)}`)
+            .then((res) => {
+                if (cancelled) return
+                setAvailable(true)
+                const data = unwrap(res)
+                const order = data?.stage_order
+                setHasCustomLayout(Array.isArray(order) && order.length > 0)
+            })
+            .catch(() => {
+                // Endpoint absent or errored — leave lane drag off.
+                if (!cancelled) setAvailable(false)
+            })
+        return () => {
+            cancelled = true
+        }
+    }, [api, model])
+
+    const save = useCallback(
+        async (order: string[]) => {
+            const res = (await api.put('/stage-layout', {
+                model,
+                stage_order: order,
+            })) as { data?: { success?: boolean; message?: string } }
+            if (res?.data && res.data.success === false) {
+                throw new Error(res.data.message || 'stage_layout_save_failed')
+            }
+            setHasCustomLayout(true)
+        },
+        [api, model],
+    )
+
+    const reset = useCallback(async () => {
+        await api.delete(`/stage-layout?model=${encodeURIComponent(model)}`)
+        setHasCustomLayout(false)
+    }, [api, model])
+
+    return { available, hasCustomLayout, save, reset }
+}

package/src/stage-overrides.ts

@@ -0,0 +1,95 @@
+// Stage overrides — per-org customization of a model's DECLARED kanban lanes
+// (Backlog, Done, …). A user can rename a lane, recolor it, and attach extra
+// "conditions" (a field/operator/value builder) that narrow which cards the lane
+// shows and counts — all without touching the addon manifest. The chosen values
+// are stored server-side and the kernel serves each declared stage already
+// carrying the overridden label/color (+ an `overridden` flag and the extra
+// `filters`), so the board paints them straight from `metadata.stages`.
+//
+// Custom stages (`custom: true`) are NOT edited here — they keep their own CRUD
+// (`/custom-stages`); this hook only owns the DECLARED-lane overrides.
+//
+// Non-intrusive by design: mirrors `useStageLayout`. If the host wires no
+// `/stage-overrides` endpoint, the GET 404s, `available` stays false, and the
+// per-lane gear (⚙) simply never renders on declared stages — the kanban keeps
+// working untouched.
+//
+// Contract (matches the ops backend; envelope is {success, data} → read .data):
+//   GET    /stage-overrides?model=<m>                  → [{ stage_key, label?, color?, filters? }] | null
+//   PUT    /stage-overrides   { model, stage_key, label?, color?, filters? }   (upsert)
+//   DELETE /stage-overrides?model=<m>&stage_key=<k>    → reset the lane to its declared default
+import { useCallback, useEffect, useState } from 'react'
+import { useApi } from './api-context'
+import type { CustomStageFilter } from './custom-stages'
+
+/** Fields a stage override can carry. All optional — send only what changed. */
+export interface StageOverridePatch {
+    label?: string
+    color?: string
+    /** Extra lane conditions (same shape/ops as smart-lane filters). */
+    filters?: CustomStageFilter[]
+}
+
+export interface UseStageOverridesResult {
+    /** True only after a successful GET — gates the per-lane gear on declared stages. */
+    available: boolean
+    /** Upsert a declared lane's override (label/color/conditions). Throws on failure. */
+    save: (stageKey: string, patch: StageOverridePatch) => Promise<void>
+    /** Reset a declared lane to its manifest default (drops the stored override). */
+    reset: (stageKey: string) => Promise<void>
+}
+
+/**
+ * Learns whether the host wired `/stage-overrides` (so the gear can appear on
+ * declared lanes) and exposes save/reset. A missing endpoint degrades to
+ * `available: false`; a real save/reset failure re-throws so the caller can
+ * surface an error + revert. The overridden VALUES themselves are read off
+ * `metadata.stages` (the kernel applies them), so this hook doesn't cache a list.
+ */
+export function useStageOverrides(model: string): UseStageOverridesResult {
+    const api = useApi()
+    const [available, setAvailable] = useState(false)
+
+    useEffect(() => {
+        let cancelled = false
+        api
+            .get(`/stage-overrides?model=${encodeURIComponent(model)}`)
+            .then(() => {
+                if (!cancelled) setAvailable(true)
+            })
+            .catch(() => {
+                // Endpoint absent or errored — leave the gear off on declared lanes.
+                if (!cancelled) setAvailable(false)
+            })
+        return () => {
+            cancelled = true
+        }
+    }, [api, model])
+
+    const save = useCallback(
+        async (stageKey: string, patch: StageOverridePatch) => {
+            const res = (await api.put('/stage-overrides', {
+                model,
+                stage_key: stageKey,
+                ...patch,
+            })) as { data?: { success?: boolean; message?: string } }
+            if (res?.data && res.data.success === false) {
+                throw new Error(res.data.message || 'stage_override_save_failed')
+            }
+        },
+        [api, model],
+    )
+
+    const reset = useCallback(
+        async (stageKey: string) => {
+            await api.delete(
+                `/stage-overrides?model=${encodeURIComponent(
+                    model,
+                )}&stage_key=${encodeURIComponent(stageKey)}`,
+            )
+        },
+        [api, model],
+    )
+
+    return { available, save, reset }
+}

package/src/types.ts

@@ -77,6 +77,34 @@ export interface StageMeta {
      * Editar/Eliminar menu on it.
      */
     custom?: boolean
+    /**
+     * True when a per-org stage override (label/color/conditions) has been
+     * applied to this DECLARED lane (ops stage-overrides). The kernel serves the
+     * lane already carrying the overridden label/color; this flag only drives the
+     * "Restablecer etapa" affordance in the config dialog. Absent on hosts without
+     * stage overrides — purely additive.
+     */
+    overridden?: boolean
+    /**
+     * Extra per-lane conditions layered on top of the stage's own `group_by`
+     * scope (ops stage-overrides). When present the lane queries its data — and
+     * counts its header — with the stage filter PLUS these conditions (serialized
+     * the same way as smart-lane filters). The lane stays a normal drop target;
+     * dropping a card only sets the stage value. Absent → the lane behaves as a
+     * plain declared stage. Snake_case ops as the kernel serves them.
+     */
+    filters?: { field: string; op: string; value: string }[]
+    /**
+     * The manifest ORIGINAL (pre-override) label/color/conditions, served
+     * alongside an overridden declared lane so the "Restablecer al original"
+     * confirm can spell out exactly what reverts. Optional — hosts that don't
+     * snapshot the original simply omit it and the SDK shows a generic confirm.
+     */
+    original?: {
+        label?: string
+        color?: string
+        filters?: { field: string; op: string; value: string }[]
+    }
 }
 
 /**