@crombolo/core 0.62.0 → 0.64.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crombolo/core",
3
- "version": "0.62.0",
3
+ "version": "0.64.0",
4
4
  "description": "Internal to crombolo, with no compatibility promise: use @crombolo/crombolo. Domain model, entity keys and shared contracts for crombolo. No I/O.",
5
5
  "license": "MIT",
6
6
  "author": "Crombolo",
@@ -29,6 +29,6 @@
29
29
  "access": "public"
30
30
  },
31
31
  "dependencies": {
32
- "@crombolo/common": "0.62.0"
32
+ "@crombolo/common": "0.64.0"
33
33
  }
34
34
  }
package/src/blocks.ts ADDED
@@ -0,0 +1,154 @@
1
+ /**
2
+ * Block values (story 345): the editors that store blocks, and the one reader of
3
+ * their layout. Rendering, the Delivery API, content files, the CLI, search and
4
+ * the alias check read blocks through it, so a block editor is added here once
5
+ * rather than once in each of them.
6
+ */
7
+ export const BLOCK_LIST_EDITOR_ALIAS = 'Umbraco.BlockList'
8
+ export const BLOCK_GRID_EDITOR_ALIAS = 'Umbraco.BlockGrid'
9
+ export const SINGLE_BLOCK_EDITOR_ALIAS = 'Umbraco.SingleBlock'
10
+ /** Rich text's, whose blocks are its value's `blocks`; `property-values.ts` names it too. */
11
+ const RICH_TEXT_EDITOR_ALIAS = 'Umbraco.RichText'
12
+
13
+ /** Editors whose stored value is a block value, its layout under the editor's alias. */
14
+ export const BLOCK_VALUE_EDITORS: ReadonlySet<string> = new Set([
15
+ BLOCK_LIST_EDITOR_ALIAS,
16
+ BLOCK_GRID_EDITOR_ALIAS,
17
+ SINGLE_BLOCK_EDITOR_ALIAS,
18
+ ])
19
+
20
+ /** Every editor whose value holds blocks: those, and rich text, whose blocks are its `blocks`. */
21
+ export const BLOCK_EDITORS: ReadonlySet<string> = new Set([
22
+ ...BLOCK_VALUE_EDITORS,
23
+ RICH_TEXT_EDITOR_ALIAS,
24
+ ])
25
+
26
+ /** Editors that hold any number of blocks, in order; a Single Block holds one. */
27
+ export const BLOCK_LIST_EDITORS: ReadonlySet<string> = new Set([
28
+ BLOCK_LIST_EDITOR_ALIAS,
29
+ BLOCK_GRID_EDITOR_ALIAS,
30
+ ])
31
+
32
+ export interface BlockData {
33
+ key: string
34
+ contentTypeKey: string
35
+ values?: Array<{
36
+ alias: string
37
+ value: unknown
38
+ editorAlias?: string
39
+ culture?: string | null
40
+ segment?: string | null
41
+ }>
42
+ }
43
+
44
+ export interface BlockLayoutEntry {
45
+ contentKey?: string
46
+ settingsKey?: string | null
47
+ /** The name it was given on its page (story 253). */
48
+ alias?: unknown
49
+ columnSpan?: number
50
+ rowSpan?: number
51
+ areas?: Array<{ key: string; items?: BlockLayoutEntry[] }>
52
+ }
53
+
54
+ export interface BlockValue {
55
+ layout?: Record<string, BlockLayoutEntry[] | undefined>
56
+ contentData?: BlockData[]
57
+ settingsData?: BlockData[]
58
+ }
59
+
60
+ /** One block: its layout entry, its content and settings, and a grid block's areas. */
61
+ export interface Block {
62
+ layout: BlockLayoutEntry
63
+ content: BlockData | undefined
64
+ settings: BlockData | undefined
65
+ areas: Array<{ key: string; blocks: Block[] }>
66
+ }
67
+
68
+ const isRecord = (value: unknown): value is Record<string, unknown> =>
69
+ typeof value === 'object' && value !== null && !Array.isArray(value)
70
+
71
+ const parsed = (value: unknown): unknown => {
72
+ if (typeof value !== 'string') return value
73
+ try {
74
+ return JSON.parse(value)
75
+ } catch {
76
+ return undefined
77
+ }
78
+ }
79
+
80
+ /** Whether a value, parsed, has the shape of a block value. */
81
+ export function isBlockValue(value: unknown): value is BlockValue {
82
+ const found = parsed(value)
83
+ return isRecord(found) && isRecord(found.layout)
84
+ }
85
+
86
+ /**
87
+ * The block value an editor's stored value holds: the value itself for a block
88
+ * editor, rich text's `blocks`, or undefined. JSON text is parsed.
89
+ */
90
+ export function blockValueOf(editorAlias: string, value: unknown): BlockValue | undefined {
91
+ const found = parsed(value)
92
+ if (!isRecord(found)) return undefined
93
+ const block = editorAlias === RICH_TEXT_EDITOR_ALIAS ? parsed(found.blocks) : found
94
+ return isBlockValue(block) ? (block as BlockValue) : undefined
95
+ }
96
+
97
+ /**
98
+ * A block value's blocks under `layoutKey`, or under every key when none is
99
+ * given, in order, each with its content and settings and a grid block's areas.
100
+ * A layout entry whose content is missing is still listed, with none.
101
+ */
102
+ export function readBlocks(value: unknown, layoutKey?: string): Block[] {
103
+ const found = parsed(value)
104
+ if (!isBlockValue(found)) return []
105
+ const block = found as BlockValue
106
+ const contents = new Map((block.contentData ?? []).map((d) => [d.key, d]))
107
+ const settings = new Map((block.settingsData ?? []).map((d) => [d.key, d]))
108
+ const build = (entries: unknown): Block[] =>
109
+ (Array.isArray(entries) ? entries : []).filter(isRecord).map((entry) => {
110
+ const layout = entry as BlockLayoutEntry
111
+ return {
112
+ layout,
113
+ content: contents.get(layout.contentKey ?? ''),
114
+ settings: settings.get(layout.settingsKey ?? ''),
115
+ areas: (Array.isArray(layout.areas) ? layout.areas : [])
116
+ .filter(isRecord)
117
+ .map((area) => ({ key: String(area.key ?? ''), blocks: build(area.items) })),
118
+ }
119
+ })
120
+ const layouts = block.layout ?? {}
121
+ return layoutKey === undefined
122
+ ? Object.values(layouts).flatMap((entries) => build(entries))
123
+ : build(layouts[layoutKey])
124
+ }
125
+
126
+ /** Each list of blocks in a value: its own, and each grid area's, at any depth. */
127
+ export function blockLists(value: unknown, layoutKey?: string): Block[][] {
128
+ const out: Block[][] = []
129
+ const walk = (blocks: Block[]) => {
130
+ out.push(blocks)
131
+ for (const block of blocks) for (const area of block.areas) walk(area.blocks)
132
+ }
133
+ walk(readBlocks(value, layoutKey))
134
+ return out
135
+ }
136
+
137
+ /**
138
+ * Every block in a value, depth first: grid areas, and the blocks held in a
139
+ * block's own content and settings values, such as a list within a block.
140
+ */
141
+ export function everyBlock(value: unknown): Block[] {
142
+ const out: Block[] = []
143
+ const visit = (blocks: Block[]) => {
144
+ for (const block of blocks) {
145
+ out.push(block)
146
+ visit(block.areas.flatMap((area) => area.blocks))
147
+ for (const data of [block.content, block.settings])
148
+ for (const own of data?.values ?? [])
149
+ visit(readBlocks(blockValueOf(own.editorAlias ?? '', own.value)))
150
+ }
151
+ }
152
+ visit(readBlocks(value))
153
+ return out
154
+ }
package/src/index.ts CHANGED
@@ -14,6 +14,7 @@ export {
14
14
  Result,
15
15
  } from '@crombolo/common'
16
16
  export * from './api-paths.ts'
17
+ export * from './blocks.ts'
17
18
  export * from './content-types.ts'
18
19
  export * from './dictionary-words.ts'
19
20
  export * from './documents.ts'
@@ -26,6 +27,7 @@ export * from './media-access.ts'
26
27
  export * from './notifications.ts'
27
28
  export * from './object-types.ts'
28
29
  export * from './paging.ts'
30
+ export * from './permission-levels.ts'
29
31
  export * from './permission-names.ts'
30
32
  export * from './permissions.ts'
31
33
  export * from './problem-details.ts'
@@ -0,0 +1,99 @@
1
+ /**
2
+ * Permission levels (story 338): what the group editor offers in place of a
3
+ * checkbox per verb. A level is a named set of verbs, never stored: the editor
4
+ * writes a level's verbs, and reads a group's verbs back as the level they
5
+ * match, or `custom`. Each kind's levels are cumulative.
6
+ */
7
+ import {
8
+ DocumentPermissions as D,
9
+ ElementPermissions as E,
10
+ FormPermissions as F,
11
+ MediaPermissions as M,
12
+ } from './permissions.ts'
13
+
14
+ export type PermissionKind = 'pages' | 'library' | 'media' | 'forms'
15
+
16
+ export const PAGE_LEVELS = ['none', 'see', 'edit', 'publish', 'full'] as const
17
+ export const MEDIA_LEVELS = ['none', 'see', 'edit'] as const
18
+ export const FORM_LEVELS = ['none', 'see', 'manage'] as const
19
+
20
+ export type PermissionLevel = 'none' | 'see' | 'edit' | 'publish' | 'full' | 'manage'
21
+
22
+ const cumulative = (steps: readonly (readonly string[])[]) =>
23
+ steps.map((_, i) => steps.slice(0, i + 1).flat())
24
+
25
+ const PAGES = cumulative([
26
+ [],
27
+ [D.Read],
28
+ [D.Create, D.Update, D.Move, D.Duplicate, D.Sort, D.PropertyValueWrite],
29
+ [D.Publish, D.Unpublish, D.Rollback],
30
+ [D.Delete, D.RecycleBinRestore, D.PublicAccess, D.CultureAndHostnames, D.Permissions],
31
+ ])
32
+
33
+ const LIBRARY = cumulative([
34
+ [],
35
+ [E.Read],
36
+ [E.Create, E.Update, E.Move, E.Duplicate],
37
+ [E.Publish, E.Unpublish, E.Rollback],
38
+ [E.Delete],
39
+ ])
40
+
41
+ const MEDIA = cumulative([[], [M.Read], [M.Update]])
42
+
43
+ const FORMS = cumulative([[], [F.View, F.EntriesView], [F.Manage, F.EntriesManage]])
44
+
45
+ /** Sensitive answers are a toggle beside a Forms level, not a level of their own. */
46
+ export const SENSITIVE_ANSWERS = F.EntriesSensitive
47
+
48
+ const TABLE: Record<PermissionKind, { levels: readonly PermissionLevel[]; verbs: string[][] }> = {
49
+ pages: { levels: PAGE_LEVELS, verbs: PAGES },
50
+ library: { levels: PAGE_LEVELS, verbs: LIBRARY },
51
+ media: { levels: MEDIA_LEVELS, verbs: MEDIA },
52
+ forms: { levels: FORM_LEVELS, verbs: FORMS },
53
+ }
54
+
55
+ /** Every verb a kind's levels speak for: what the editor owns of a group's verbs. */
56
+ export const kindVerbs = (kind: PermissionKind): readonly string[] => TABLE[kind].verbs.at(-1) ?? []
57
+
58
+ /** The levels a kind offers, in order. */
59
+ export const levelsOf = (kind: PermissionKind): readonly PermissionLevel[] => TABLE[kind].levels
60
+
61
+ /** The verbs a level stands for. */
62
+ export function levelVerbs(kind: PermissionKind, level: PermissionLevel): string[] {
63
+ const at = TABLE[kind].levels.indexOf(level)
64
+ if (at === -1) throw new Error(`${kind} has no level "${level}"`)
65
+ return [...(TABLE[kind].verbs[at] ?? [])]
66
+ }
67
+
68
+ /** The level a group's verbs are, for one kind, or `custom` when they match none. */
69
+ export function levelOfVerbs(
70
+ kind: PermissionKind,
71
+ verbs: readonly string[],
72
+ ): PermissionLevel | 'custom' {
73
+ const own = new Set(kindVerbs(kind))
74
+ const held = new Set(verbs.filter((verb) => own.has(verb)))
75
+ const { levels, verbs: sets } = TABLE[kind]
76
+ for (const [i, set] of sets.entries())
77
+ if (set.length === held.size && set.every((verb) => held.has(verb)))
78
+ return levels[i] as PermissionLevel
79
+ return 'custom'
80
+ }
81
+
82
+ /**
83
+ * A group's verbs with one kind set to a level: the kind's own verbs replaced,
84
+ * everything else kept, so a level never touches another kind or a toggle.
85
+ */
86
+ export function withLevel(
87
+ verbs: readonly string[],
88
+ kind: PermissionKind,
89
+ level: PermissionLevel,
90
+ ): string[] {
91
+ const own = new Set(kindVerbs(kind))
92
+ return [...new Set([...verbs.filter((verb) => !own.has(verb)), ...levelVerbs(kind, level)])]
93
+ }
94
+
95
+ /** A Pages verb set as the Library's, for "Same as pages". */
96
+ export function libraryLikePages(pageVerbs: readonly string[]): string[] {
97
+ const level = levelOfVerbs('pages', pageVerbs)
98
+ return level === 'custom' ? [] : levelVerbs('library', level)
99
+ }
@@ -6,7 +6,6 @@
6
6
  */
7
7
  import {
8
8
  DocumentPermissions,
9
- ElementContainerPermissions,
10
9
  ElementPermissions,
11
10
  FormPermissions,
12
11
  MediaPermissions,
@@ -57,12 +56,9 @@ export const PERMISSION_NAMES: readonly PermissionName[] = [
57
56
  Duplicate: 'Copy pages',
58
57
  Sort: 'Change the order of pages',
59
58
  Rollback: "Put back a page's earlier version",
60
- Notifications: 'Choose the notifications they get about pages',
61
59
  Permissions: 'Set who may do what on a page',
62
60
  CultureAndHostnames: "Set a page's languages and hostnames",
63
61
  PublicAccess: 'Restrict a page to members',
64
- CreateBlueprint: 'Make a blueprint from a page',
65
- PropertyValueRead: "See a page's protected values",
66
62
  PropertyValueWrite: "Change a page's protected values",
67
63
  RecycleBinRestore: 'Restore pages from the recycle bin',
68
64
  }),
@@ -77,13 +73,6 @@ export const PERMISSION_NAMES: readonly PermissionName[] = [
77
73
  Unpublish: 'Unpublish Library items',
78
74
  Rollback: "Put back a Library item's earlier version",
79
75
  }),
80
- ...area('library-folders', ElementContainerPermissions, {
81
- Read: 'See Library folders',
82
- Create: 'Create Library folders',
83
- Update: 'Rename Library folders',
84
- Delete: 'Delete Library folders',
85
- Move: 'Move Library folders',
86
- }),
87
76
  ...area('media', MediaPermissions, { Read: 'See media', Update: 'Change media' }),
88
77
  ...area('forms', formDesign, { View: 'See forms', Manage: 'Design forms' }),
89
78
  ...area(
@@ -21,12 +21,9 @@ export const DocumentPermissions = {
21
21
  Duplicate: 'Umb.Document.Duplicate',
22
22
  Sort: 'Umb.Document.Sort',
23
23
  Rollback: 'Umb.Document.Rollback',
24
- Notifications: 'Umb.Document.Notifications',
25
24
  Permissions: 'Umb.Document.Permissions',
26
25
  CultureAndHostnames: 'Umb.Document.CultureAndHostnames',
27
26
  PublicAccess: 'Umb.Document.PublicAccess',
28
- CreateBlueprint: 'Umb.Document.CreateBlueprint',
29
- PropertyValueRead: 'Umb.Document.PropertyValue.Read',
30
27
  PropertyValueWrite: 'Umb.Document.PropertyValue.Write',
31
28
  RecycleBinRestore: 'Umb.DocumentRecycleBin.Restore',
32
29
  } as const
@@ -64,13 +61,18 @@ export const RemotePermissions = {
64
61
  PullFull: 'Crombolo.Remote.PullFull',
65
62
  Push: 'Crombolo.Remote.Push',
66
63
  PushProtected: 'Crombolo.Remote.PushProtected',
67
- /** Changing a remote's schema, views, styles or code: a whole-site push, or such a bundle (story 167). */
64
+ /** Changing a remote's schema, styles or scripts: such a bundle, or a whole-site push with InstallCode (story 167). */
68
65
  ApplyStructure: 'Crombolo.Remote.ApplyStructure',
69
- /** Installing the code a bundle carries, or a bundle as a dependency, on a site (story 241). */
66
+ /** Installing a bundle's code or templates, a bundle as a dependency, or a whole-site push (stories 241, 336). */
70
67
  InstallCode: 'Crombolo.Remote.InstallCode',
71
68
  } as const
72
69
  export type RemoteVerb = (typeof RemotePermissions)[keyof typeof RemotePermissions]
73
70
 
71
+ const REMOTE_VERBS: ReadonlySet<string> = new Set(Object.values(RemotePermissions))
72
+
73
+ /** A remote verb: a group holding one is only an administrator's to fill (story 302). */
74
+ export const isRemotePermission = (verb: string): boolean => REMOTE_VERBS.has(verb)
75
+
74
76
  /**
75
77
  * Permissions an administrator does not hold by being one (story 241): only a
76
78
  * group that names them grants them, so installing code on a site is always a
@@ -103,14 +105,33 @@ export const ElementPermissions = {
103
105
  Rollback: 'Umb.Element.Rollback',
104
106
  } as const
105
107
 
106
- /** Umbraco's element folder verbs. */
107
- export const ElementContainerPermissions = {
108
- Read: 'Umb.ElementContainer.Read',
109
- Create: 'Umb.ElementContainer.Create',
110
- Update: 'Umb.ElementContainer.Update',
111
- Delete: 'Umb.ElementContainer.Delete',
112
- Move: 'Umb.ElementContainer.Move',
113
- } as const
108
+ /**
109
+ * Verbs taken out of the catalogue (story 338), each with what replaces it, or
110
+ * null where nothing does: a stored row or a group file naming one is read as
111
+ * its replacement. A Library folder is governed by the Library's own verbs;
112
+ * notifications follow seeing the page; a blueprint follows creating one; and a
113
+ * field is always shown, with only changing it governed.
114
+ */
115
+ export const PRUNED_PERMISSIONS: Readonly<Record<string, string | null>> = {
116
+ 'Umb.ElementContainer.Read': ElementPermissions.Read,
117
+ 'Umb.ElementContainer.Create': ElementPermissions.Create,
118
+ 'Umb.ElementContainer.Update': ElementPermissions.Update,
119
+ 'Umb.ElementContainer.Delete': ElementPermissions.Delete,
120
+ 'Umb.ElementContainer.Move': ElementPermissions.Move,
121
+ 'Umb.Document.CreateBlueprint': DocumentPermissions.Create,
122
+ 'Umb.Document.Notifications': null,
123
+ 'Umb.Document.PropertyValue.Read': null,
124
+ }
125
+
126
+ /** A verb list with each pruned verb replaced or dropped, and no repeats. */
127
+ export function withoutPrunedPermissions(verbs: readonly string[]): string[] {
128
+ const out = new Set<string>()
129
+ for (const verb of verbs) {
130
+ const replaced = verb in PRUNED_PERMISSIONS ? PRUNED_PERMISSIONS[verb] : verb
131
+ if (replaced !== null && replaced !== undefined) out.add(replaced)
132
+ }
133
+ return [...out]
134
+ }
114
135
 
115
136
  /** The discriminator on a granular permission row. */
116
137
  export type PermissionContext = 'Document' | 'Element' | 'DocumentTypeProperty'
@@ -122,7 +143,6 @@ export const KNOWN_PERMISSIONS: ReadonlySet<string> = new Set([
122
143
  ...Object.values(RemotePermissions),
123
144
  ...Object.values(MediaPermissions),
124
145
  ...Object.values(ElementPermissions),
125
- ...Object.values(ElementContainerPermissions),
126
146
  ])
127
147
 
128
148
  export const ADMIN_GROUP_ALIAS = 'admin'
@@ -169,31 +189,17 @@ const within = (path: StartNodePath, ancestor: StartNodePath) =>
169
189
  ancestor.length <= path.length && ancestor.every((key, i) => path[i] === key)
170
190
 
171
191
  /**
172
- * Umbraco's `CombineStartNodes`: the groups' start nodes keep the topmost, the
173
- * user's own keep the deepest, and each of the user's replaces any group start
174
- * node above or below it. Callers leave out nodes that no longer exist or are
175
- * in the recycle bin.
192
+ * Where a user may work in one tree (story 339): their groups' start nodes
193
+ * together, the topmost of any that nest. Callers leave out nodes that no longer
194
+ * exist or are in the recycle bin.
176
195
  */
177
- export function combineStartNodes(
178
- group: readonly StartNodePath[],
179
- user: readonly StartNodePath[],
180
- ): StartNodes {
196
+ export function unionStartNodes(group: readonly StartNodePath[]): StartNodes {
181
197
  let kept: StartNodePath[] = []
182
198
  for (const path of group) {
183
199
  if (kept.some((k) => within(path, k))) continue
184
200
  kept = kept.filter((k) => !within(k, path))
185
201
  kept.push(path)
186
202
  }
187
- let own: StartNodePath[] = []
188
- for (const path of user) {
189
- if (own.some((k) => within(k, path))) continue
190
- own = own.filter((k) => !within(path, k))
191
- own.push(path)
192
- }
193
- for (const path of own) {
194
- kept = kept.filter((k) => !within(path, k) && !within(k, path))
195
- kept.push(path)
196
- }
197
203
  return {
198
204
  root: kept.some((path) => path.length === 0),
199
205
  keys: kept.filter((path) => path.length > 0).map((path) => path[path.length - 1] as string),
@@ -4,6 +4,8 @@
4
4
  * stored and returned as is.
5
5
  */
6
6
 
7
+ import { BLOCK_EDITORS } from './blocks.ts'
8
+
7
9
  export const RICH_TEXT_EDITOR_ALIAS = 'Umbraco.RichText'
8
10
  export const UPLOAD_FIELD_EDITOR_ALIAS = 'Umbraco.UploadField'
9
11
  export const IMAGE_CROPPER_EDITOR_ALIAS = 'Umbraco.ImageCropper'
@@ -16,9 +18,7 @@ export const FILE_VALUE_EDITORS: ReadonlySet<string> = new Set([
16
18
 
17
19
  /** Editors whose values are objects or arrays, stored as JSON. */
18
20
  export const JSON_VALUE_EDITORS: ReadonlySet<string> = new Set([
19
- RICH_TEXT_EDITOR_ALIAS,
20
- 'Umbraco.BlockList',
21
- 'Umbraco.BlockGrid',
21
+ ...BLOCK_EDITORS,
22
22
  'Umbraco.CheckBoxList',
23
23
  'Umbraco.ColorPicker',
24
24
  'Umbraco.DateTimeWithTimeZone',