@asteby/metacore-runtime-react 23.8.0 → 23.9.0

package/src/dynamic-kanban.tsx

@@ -54,6 +54,7 @@ import {
     MoreHorizontal,
     RotateCcw,
     Search,
+    Settings2,
     Tag,
     ToggleLeft,
     Type,
@@ -99,13 +100,18 @@ import {
     splitCustomStages,
     mergeLaneStages,
     resolveSmartLanes,
+    cardMatchesStageFilters,
+    smartLaneParams,
     AddStageColumn,
-    CustomStageLaneMenu,
     CustomStageDialog,
     CustomStageDeleteDialog,
+    StageConfigDialog,
     SmartLane,
     type CustomStage,
+    type CustomStageFilter,
+    type StageConfigTarget,
 } from './custom-stages'
+import { useStageOverrides } from './stage-overrides'
 import { useDynamicFilters } from './use-dynamic-filters'
 import {
     FilterChipsRow,
@@ -489,10 +495,16 @@ export function DynamicKanban({
     // the host has no `/custom-stages` endpoint — the "+ Agregar etapa" column
     // and lane menus simply don't render.
     const customStages = useCustomStages(model)
+    // Per-org overrides for DECLARED lanes (rename/recolor/conditions). Degrades
+    // to no-op when the host has no `/stage-overrides` endpoint — the ⚙ gear then
+    // hides on declared lanes (custom lanes keep it via /custom-stages).
+    const stageOverrides = useStageOverrides(model)
     // Dialog state: create/edit a stage, and the delete confirmation.
     const [stageDialogOpen, setStageDialogOpen] = useState(false)
     const [editingStage, setEditingStage] = useState<CustomStage | null>(null)
     const [deletingStage, setDeletingStage] = useState<CustomStage | null>(null)
+    // The gear (⚙) "Configurar etapa" dialog — one UI for declared + custom lanes.
+    const [configTarget, setConfigTarget] = useState<StageConfigTarget | null>(null)
     const openCreateStage = useCallback(() => {
         setEditingStage(null)
         setStageDialogOpen(true)
@@ -628,6 +640,7 @@ export function DynamicKanban({
                         const r = (await api.get(endpoint || `/data/${model}`, {
                             params: {
                                 ...filterParams,
+                                ...smartLaneParams(stage.filters),
                                 page: 1,
                                 per_page: 1,
                                 [`f_${gb}`]: stage.key,
@@ -661,6 +674,27 @@ export function DynamicKanban({
     // the shared records. Scoped by `f_<group_by>=<stage>` on top of the active
     // filterParams (the stage scope wins over any global group_by filter).
     const groupByKey = metadata?.group_by || ''
+    // Extra per-lane conditions (stage overrides) keyed by stage. A real lane
+    // that carries these queries its data — and counts its header — with the
+    // stage scope PLUS these filters (serialized like a smart lane's), so the
+    // top-up + eager-total requests below layer them on. Sourced from
+    // `metadata.stages` (the kernel applies declared + custom-real overrides).
+    const stageExtraFilters = useMemo(() => {
+        const m = new Map<string, CustomStageFilter[]>()
+        for (const s of metadata?.stages ?? []) {
+            if (s.filters && s.filters.length > 0) {
+                m.set(
+                    s.key,
+                    s.filters.map((f) => ({
+                        field: f.field,
+                        op: f.op as CustomStageFilter['op'],
+                        value: f.value,
+                    })),
+                )
+            }
+        }
+        return m
+    }, [metadata?.stages])
     const loadMoreLane = useCallback(
         async (stageKey: string) => {
             if (!metadata || !groupByKey) return
@@ -680,6 +714,7 @@ export function DynamicKanban({
                 const res = (await api.get(endpoint || `/data/${model}`, {
                     params: {
                         ...filterParams,
+                        ...smartLaneParams(stageExtraFilters.get(stageKey)),
                         page: nextPage,
                         per_page: lanePageSize,
                         [`f_${groupByKey}`]: stageKey,
@@ -712,7 +747,7 @@ export function DynamicKanban({
                 }))
             }
         },
-        [api, endpoint, model, metadata, groupByKey, filterParams, lanePageSize, lanePagination],
+        [api, endpoint, model, metadata, groupByKey, filterParams, lanePageSize, lanePagination, stageExtraFilters],
     )
 
     // Refetch when metadata resolves, on an explicit refresh, or when the
@@ -1133,14 +1168,82 @@ export function DynamicKanban({
         stageKey === activeStage ||
         isTransitionAllowed(transitions, activeStage, stageKey)
 
+    // Opens the gear (⚙) "Configurar etapa" dialog for a lane, routing to the
+    // right backend by kind: a custom real stage edits through /custom-stages, a
+    // declared stage through /stage-overrides. Seeds the current label/color and
+    // any extra conditions the lane already carries.
+    const openConfigStage = (stage: StageMeta) => {
+        const custom = customStages.available
+            ? customByKey.get(stage.key)
+            : undefined
+        const raw =
+            stageExtraFilters.get(stage.key) ??
+            (custom?.filters as CustomStageFilter[] | undefined) ??
+            []
+        const filters: CustomStageFilter[] = raw.map((f) => ({
+            field: f.field,
+            op: f.op as CustomStageFilter['op'],
+            value: f.value,
+        }))
+        if (custom) {
+            setConfigTarget({
+                kind: 'custom',
+                stageKey: stage.key,
+                id: custom.id,
+                label: custom.label,
+                color: custom.color,
+                filters,
+                customStage: custom,
+            })
+        } else {
+            const original = stage.original
+                ? {
+                      label: stage.original.label,
+                      color: stage.original.color,
+                      filters: stage.original.filters?.map((f) => ({
+                          field: f.field,
+                          op: f.op as CustomStageFilter['op'],
+                          value: f.value,
+                      })),
+                  }
+                : undefined
+            setConfigTarget({
+                kind: 'declared',
+                stageKey: stage.key,
+                label: t(stage.label, { defaultValue: stage.label }),
+                color: stage.color ?? 'slate',
+                filters,
+                overridden: !!stage.overridden,
+                isFinal: stage.is_final,
+                original,
+            })
+        }
+    }
+    // Whether a lane offers the gear: custom real stages always (their CRUD is
+    // wired); declared lanes only when the host wired /stage-overrides. Never on
+    // the synthetic "Sin etapa" lane.
+    const isConfigurable = (stage: StageMeta): boolean => {
+        if (stage.key === UNASSIGNED_LANE) return false
+        return customByKey.has(stage.key)
+            ? customStages.available
+            : stageOverrides.available
+    }
+
     // Builds every `KanbanLane` prop (minus the dnd wiring) for one stage —
     // shared by the sortable real stages and the plain-droppable unassigned lane.
     const buildLaneProps = (stage: StageMeta): Omit<KanbanLaneProps, 'dnd'> => {
         const allCards = grouped.get(stage.key) ?? []
+        // Extra lane conditions (stage override): the server already scopes this
+        // lane's top-up + total queries by them, but the shared INITIAL board page
+        // is unscoped, so narrow those cards client-side too (belt-and-suspenders).
+        const extraFilters = stageExtraFilters.get(stage.key) ?? []
         // Per-lane client-side narrowing (instant, scoped to this stage). The
         // funnel (field/value) and the lane search (query) are AND-combined.
         const laneFilter = laneFilters[stage.key]
         let cards = allCards
+        if (extraFilters.length > 0) {
+            cards = cards.filter((c) => cardMatchesStageFilters(c, extraFilters))
+        }
         if (laneFilter?.field) {
             cards = cards.filter((c) => cardMatchesLaneFunnel(c, laneFilter))
         }
@@ -1179,11 +1282,9 @@ export function DynamicKanban({
             onAutomationCreate: automations.create,
             onAutomationUpdate: automations.update,
             onAutomationRemove: automations.remove,
-            customStage: customStages.available
-                ? customByKey.get(stage.key)
-                : undefined,
-            onEditStage: openEditStage,
-            onDeleteStage: openDeleteStage,
+            extraFilters,
+            configurable: isConfigurable(stage),
+            onConfigure: () => openConfigStage(stage),
             children:
                 loadingData && cards.length === 0 ? (
                     <>
@@ -1461,6 +1562,50 @@ export function DynamicKanban({
                     />
                 </>
             )}
+
+            {/* Unified "Configurar etapa" dialog opened by the per-lane ⚙ gear —
+                routes saves to /stage-overrides (declared) or /custom-stages
+                (custom) by the target's kind. */}
+            <StageConfigDialog
+                open={!!configTarget}
+                onOpenChange={(o) => {
+                    if (!o) setConfigTarget(null)
+                }}
+                columns={metadata?.columns ?? []}
+                target={configTarget}
+                onSaveOverride={async (stageKey, patch) => {
+                    await stageOverrides.save(stageKey, patch)
+                    // The override changes the served label/color/filters — refetch
+                    // metadata so the board repaints, and reload the cards.
+                    try {
+                        const res = await api.get(`/metadata/table/${model}`)
+                        const body = res.data as ApiResponse<TableMetadata>
+                        if (body.success) {
+                            setMetadata(body.data)
+                            cacheMetadata(model, body.data)
+                        }
+                    } catch {
+                        /* keep the current metadata on a refetch miss */
+                    }
+                    void fetchData()
+                }}
+                onResetOverride={async (stageKey) => {
+                    await stageOverrides.reset(stageKey)
+                    try {
+                        const res = await api.get(`/metadata/table/${model}`)
+                        const body = res.data as ApiResponse<TableMetadata>
+                        if (body.success) {
+                            setMetadata(body.data)
+                            cacheMetadata(model, body.data)
+                        }
+                    } catch {
+                        /* keep the current metadata on a refetch miss */
+                    }
+                    void fetchData()
+                }}
+                onUpdateCustom={customStages.update}
+                onDeleteCustom={openDeleteStage}
+            />
         </div>
     )
 }
@@ -1716,10 +1861,12 @@ interface KanbanLaneProps {
         patch: Partial<StageAutomation>,
     ) => Promise<void>
     onAutomationRemove: (id: StageAutomation['id']) => Promise<void>
-    /** When set, this lane is a user-defined custom stage → show ⋮ Editar/Eliminar. */
-    customStage?: CustomStage
-    onEditStage?: (stage: CustomStage) => void
-    onDeleteStage?: (stage: CustomStage) => void
+    /** Extra lane conditions (stage override) — drives the header filter dot + tooltip. */
+    extraFilters: CustomStageFilter[]
+    /** Whether the ⚙ "Configurar etapa" gear should render for this lane. */
+    configurable: boolean
+    /** Opens the gear config dialog for this lane. */
+    onConfigure: () => void
     children: React.ReactNode
 }
 
@@ -1745,9 +1892,9 @@ function KanbanLane({
     onAutomationCreate,
     onAutomationUpdate,
     onAutomationRemove,
-    customStage,
-    onEditStage,
-    onDeleteStage,
+    extraFilters,
+    configurable,
+    onConfigure,
     children,
 }: KanbanLaneProps) {
     const { t } = useTranslation()
@@ -1792,6 +1939,25 @@ function KanbanLane({
           }
         : undefined
 
+    // Stage-override conditions active on this lane → a small filter dot in the
+    // header, its `title` listing the conditions (e.g. "priority es igual high").
+    const hasConditions = extraFilters.length > 0
+    const conditionsSummary = extraFilters
+        .map((f) => {
+            const opLabel = t(`dynamic.custom_stages.op.${f.op}`, {
+                defaultValue:
+                    f.op === 'eq'
+                        ? 'es igual'
+                        : f.op === 'neq'
+                        ? 'distinto'
+                        : f.op === 'contains'
+                        ? 'contiene'
+                        : 'en lista',
+            })
+            return `${f.field} ${opLabel} ${f.value}`
+        })
+        .join(' · ')
+
     return (
         <div
             ref={dnd.setNodeRef}
@@ -1836,6 +2002,22 @@ function KanbanLane({
                     <span className="text-xs font-medium tabular-nums text-muted-foreground">
                         {formatLaneCount(count, totalCount, serverTotal, laneActive)}
                     </span>
+                    {hasConditions && (
+                        <span
+                            className="flex items-center text-primary"
+                            title={t('dynamic.stage_config.conditions_active', {
+                                defaultValue: 'Condiciones: {{list}}',
+                                list: conditionsSummary,
+                            })}
+                            data-testid={`lane-conditions-${stage.key}`}
+                            aria-label={t('dynamic.stage_config.conditions_active', {
+                                defaultValue: 'Condiciones: {{list}}',
+                                list: conditionsSummary,
+                            })}
+                        >
+                            <ListFilter className="h-3 w-3" />
+                        </span>
+                    )}
                 </div>
                 {/* Lane actions — always visible in muted (a hidden hover-reveal
                     was undiscoverable); active state is a primary tint + a count
@@ -1873,12 +2055,20 @@ function KanbanLane({
                             onRemove={onAutomationRemove}
                         />
                     )}
-                    {customStage && onEditStage && onDeleteStage && (
-                        <CustomStageLaneMenu
-                            stage={customStage}
-                            onEdit={onEditStage}
-                            onDelete={onDeleteStage}
-                        />
+                    {configurable && (
+                        <button
+                            type="button"
+                            onClick={onConfigure}
+                            className={`relative flex size-6 items-center justify-center rounded-md transition-colors hover:bg-accent hover:text-foreground ${
+                                hasConditions ? 'text-primary' : 'text-muted-foreground'
+                            }`}
+                            aria-label={t('dynamic.stage_config.open', {
+                                defaultValue: 'Configurar etapa',
+                            })}
+                            data-testid={`lane-config-${stage.key}`}
+                        >
+                            <Settings2 className="h-3.5 w-3.5" />
+                        </button>
                     )}
                 </div>
             </div>

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,12 +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-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 }[]
+    }
 }
 
 /**