@01-edu/shared 1.0.12 → 1.1.1

package/attrs-defs.js

@@ -7,6 +7,7 @@ import {
   getQuestStartAt,
   numTime,
 } from './event-utils.js'
+import { flatGraphContents, getCoreOfSattelite, limitations } from './graph.js'
 import { onboardingTypes } from './onboarding.js'
 import { getObjectFromRelativePath } from './path.js'
 import { gamesScoring } from './score.js'
@@ -61,22 +62,12 @@ const firstOfGroup = (a, _i, children) => {
   return children.find(b => b.attrs.group === group) === a
 }
 
-const getCoreName = object => {
-  const corePath = object.attrs.requirements?.core
-  const core = _children(object.parent).find(
-    child =>
-      child.id ===
-      getObjectFromRelativePath(corePath, object, { throwError: false })?.id,
-  )
-  return core?.name || ''
-}
-
 const getObjectPath = object => {
-  const { attrs, name } = object
-  if (!attrs.requirements?.core) return name
+  const core = getCoreOfSattelite(object)
+  if (!core) return object.name
   // special case only for projects with a core requirement set
-  const coreName = getCoreName(object)
-  const path = `${coreName}/${getProjectName(object)}`
+  // const coreName = getCoreName(object)
+  const path = `${core.name}/${getProjectName(object)}`
   return path
 }
 
@@ -129,6 +120,7 @@ const TypeObject = def => ({
 //    required: // if the attribute is always there by default,
 //    editable: // if it can be override by schools in the db (=/= choice in between several functions),
 //    private: // if the attribute should not be seen in front end,
+//    hidden: // if the attribute should be hidden to admins but needed in front end,
 //    primary: // only used objects in arrays, allow to indicate what key must have a unique value
 //    options: // array containing literal possible values
 //    acceptDuplicates: // when array type can have duplicates
@@ -927,15 +919,13 @@ relationAttrs.difficultyMod = {
 
 const getName = ({ name }) => name
 const getProjectName = object => {
-  const { name, attrs } = object
-  if (!attrs.requirements?.core) return name
-  // only for projects with a core requirement set, and which name starts by the core name:
+  const core = getCoreOfSattelite(object)
+  if (!core) return object.name
+  // only for projects with a core, and which name starts by the core name:
   // remove the core name from the name to avoid repetition
-  const coreName = getCoreName(object)
-  // TODO: couldn't we just display the key?
-  return coreName && name.startsWith(coreName)
-    ? name.slice(coreName.length + 1)
-    : name
+  return core.name && object.name.startsWith(core.name)
+    ? object.name.slice(core.name.length + 1)
+    : object.name
 }
 const sharedDisplayedName = Literal('', {
   editable: true,
@@ -978,7 +968,7 @@ const sharedDuration = Literal(1, {
 relationAttrs.duration = {
   // TODO: rm, here just for campus comparison
   module: {
-    exam: sharedDuration,
+    exam: { ...sharedDuration, hidden: true },
   },
   piscine: {
     quest: sharedDuration,
@@ -1628,24 +1618,306 @@ attrs.grade = {
   }),
 }
 
-types.moduleGraphViews = {
-  type: 'string',
-  options: ['Circular', 'Linear'],
-  editable: true,
-  value: '',
+/* MODULE GRAPH ATTRIBUTE */
+types.graphArcName = TypeObject({
+  label: 'Name of the arc',
+  type: {
+    text: Literal('', {
+      label: 'The text name of the arc',
+      type: 'string',
+    }),
+    hidden: Literal(true, {
+      label: 'Display the text name on the graph',
+    }),
+  },
+})
+
+const checkGraphArcContentIsValid = (contentName, object) => {
+  const matchingObject = object.children[contentName]
+  if (!matchingObject) {
+    throw Error(
+      `Invalid object - no object found in the module for the following key name: ${contentName}`,
+    )
+  }
 }
-attrs.graphView = {
-  module: {
-    value: [],
-    editable: true,
-    label: 'Graph views',
-    type: [types.moduleGraphViews],
-    check: value => {
-      if (value.length === 0) throw Error('Must contain at least one view')
-      if (new Set(value).size !== value.length)
-        throw Error('Should not contain duplicates')
+
+types.graphArcContentName = Literal('', {
+  label: 'The text name of a content placed on an arc',
+  check: (contentName, object) =>
+    checkGraphArcContentIsValid(contentName, object),
+})
+
+types.graphArcContentWithSubContents = {
+  value: {},
+  label: 'Content with sub-contents placed on an arc',
+  type: 'object',
+  check: (value, object) => {
+    if (isntObjectOrIsEmpty(value)) {
+      throw Error('Should be a non empty object.')
+    }
+
+    const entries = Object.entries(value)
+    if (entries.length > 1) {
+      throw Error(
+        "Should be an object with a single key-value pair; the key being the content's name, and the value being an array of sub-contents's names.",
+      )
+    }
+
+    const [contentName, subContentsList] = entries[0]
+
+    // check content name key matches an existing object in the module
+    checkGraphArcContentIsValid(contentName, object)
+
+    // check sub-contents' list is a non empty array
+    if (!Array.isArray(subContentsList) || !subContentsList.length) {
+      throw Error('Must be a non empty array')
+    }
+
+    // check there's no duplicates in sub-contents' list
+    const uniques = new Set(subContentsList)
+    if (subContentsList.length !== uniques.size) {
+      throw Error('Duplicates are not allowed.')
+    }
+
+    const maxSattelitesAllowed =
+      limitations.SLICE.innerCircle.maxSubContentsCount
+    if (subContentsList.length > maxSattelitesAllowed) {
+      throw Error('Max sattelites reached')
+    }
+
+    // check sub-contents' name keys match existing objects in the module
+    for (const keyName of subContentsList) {
+      checkGraphArcContentIsValid(keyName, object)
+    }
+  },
+}
+
+const graphArcBasicChecks = value => {
+  const { name: _name, contents, type: _type, id: _id, ...rest } = value
+
+  if (Object.keys(rest).length) {
+    throw Error(`Unsupported attribute "${Object.keys(rest)[0]}"`)
+  }
+
+  if (!Array.isArray(contents) || !contents?.length) {
+    throw Error('Must be a non empty array')
+  }
+}
+
+types.graphArc = TypeObject({
+  label: 'Name & contents of an arc',
+  type: {
+    id: Literal('', {
+      label: 'A randomly-generated id to identify the arc',
+    }),
+    name: types.graphArcName,
+    contents: {
+      label: 'The list of contents to be placed on an arc',
+      type: [types.graphArcContentName],
+    },
+  },
+  check: graphArcBasicChecks,
+})
+
+types.innerCircleSlice = TypeObject({
+  label: 'Slice on the inner circle',
+  type: {
+    id: Literal('', {
+      label: 'A randomly-generated id to identify the slice',
+    }),
+    name: types.graphArcName,
+
+    type: Literal('slice', {
+      label: 'The slice type',
+    }),
+
+    entryPoint: types.graphArcContentName,
+
+    innerArc: TypeObject({
+      label: 'Inner arc of an inner circle slice',
+      type: {
+        ...types.graphArc.type,
+        contents: {
+          label:
+            'The list of contents to be placed on an inner arc of an inner circle slice',
+          type: [
+            types.graphArcContentName,
+            types.graphArcContentWithSubContents, // for now, sub-contents are only displayed on the inner arc of an inner circle slice
+          ],
+        },
+      },
+      check: graphArcBasicChecks,
+    }),
+
+    outerArcs: {
+      label: 'Outer arcs of an inner circle slice',
+      type: [types.graphArc],
+      check: outerArcs => {
+        const { maxArcsCount, maxContentsCount } = limitations.SLICE.outerArc
+        if (outerArcs.length > maxArcsCount) {
+          throw Error('Max outerArcs reached')
+        }
+        if (
+          outerArcs.reduce(
+            (total, arc) => total + (arc.contents?.length || 0),
+            0,
+          ) > maxContentsCount
+        ) {
+          throw Error('Max contents spread over outerArcs of slice reached')
+        }
+      },
     },
   },
+
+  check: innerCircle => {
+    const { name, entryPoint, type, innerArc, outerArcs, id, ...rest } =
+      innerCircle
+
+    if (Object.keys(rest).length) {
+      throw Error(`Unsupported attribute "${Object.keys(rest)[0]}"`)
+    }
+
+    if (!name && !entryPoint && !type && !innerArc && !outerArcs && !id) {
+      throw Error('Empty inner circle, should be removed')
+    }
+  },
+})
+
+types.innerCircleLine = {
+  ...types.graphArc,
+  label: 'Line on the inner circle',
+  type: {
+    ...types.graphArc.type,
+    type: Literal('line', {
+      label: 'The line type',
+    }),
+  },
+  check: line => {
+    if (line.contents.length > limitations.LINE.maxContentsCount) {
+      throw Error('Max contents reached for a line')
+    }
+  },
+}
+
+const graphStructure = TypeObject({
+  private: true, // not displayed in the admin settings; could use hidden too but private more efficient
+  required: true,
+  editable: true, // TODO: check if should be here?
+  value: { innerCircle: [], middleCircle: [], outerCircle: [] },
+  label: 'Graph structure',
+  instruction: 'Structure of the visual graph',
+  description:
+    'Sets the visual structure & hierarchy of the graph of a module.',
+  type: {
+    centralPoint: types.graphArcContentName,
+
+    innerCircle: {
+      value: [],
+      required: true,
+      editable: true,
+      label: 'List of slices and/or lines spread on the inner circle',
+      type: [types.innerCircleSlice, types.innerCircleLine],
+      check: innerCircle => {
+        const slices = innerCircle.filter(section => section.type === 'slice')
+        const lines = innerCircle.filter(section => section.type === 'line')
+        const { SLICE, LINE } = limitations
+        if (slices.length > SLICE.maxSlicesCount) {
+          throw Error('Max slices sections reached')
+        }
+        if (lines.length > LINE.maxLinesCount) {
+          throw Error('Max lines sections reached')
+        }
+        if (
+          slices.flatMap(({ innerArc }) =>
+            innerArc.contents.flatMap(c =>
+              typeof c === 'string' ? c : Object.keys(c)[0],
+            ),
+          ).length > SLICE.innerCircle.maxContentsCount
+        ) {
+          throw Error('Max contents spread over innerArcs of slices reached')
+        }
+      },
+    },
+
+    middleCircle: {
+      value: [],
+      required: true,
+      editable: true,
+      label: 'List of arcs spread on the middle circle',
+      type: [types.graphArc],
+      check: middleCircle => {
+        const { maxArcsCount, maxContentsCount } = limitations.MIDDLE_CIRCLE
+        if (middleCircle.length > maxArcsCount) {
+          throw Error('Max arches reach on middleCircle')
+        }
+        if (
+          middleCircle.reduce(
+            (total, arc) => total + (arc.contents?.length || 0),
+            0,
+          ) > maxContentsCount
+        ) {
+          throw Error('Max contents reach on middleCircle')
+        }
+      },
+    },
+
+    outerCircle: {
+      value: [],
+      required: true,
+      editable: true,
+      label: 'List of arcs spread on the outer circle',
+      type: [types.graphArc],
+      check: outerCircle => {
+        const { maxArcsCount, maxContentsCount } = limitations.OUTER_CIRCLE
+        if (outerCircle.length > maxArcsCount) {
+          throw Error('Max arches reach on outerCircle')
+        }
+        if (
+          outerCircle.reduce(
+            (total, arc) => total + (arc.contents?.length || 0),
+            0,
+          ) > maxContentsCount
+        ) {
+          throw Error('Max contents reach on outerCircle')
+        }
+      },
+    },
+  },
+  check: (graph, object) => {
+    const { centralPoint, innerCircle, middleCircle, outerCircle, ...rest } =
+      graph
+
+    if (Object.keys(rest).length) {
+      throw Error(`Unsupported attribute "${Object.keys(rest)[0]}"`)
+    }
+
+    if (
+      !centralPoint &&
+      !innerCircle?.length &&
+      !middleCircle?.length &&
+      !outerCircle?.length
+    ) {
+      throw Error('Empty graph, should be removed')
+    }
+    const flattenContents = flatGraphContents(graph)
+    const flattenContentsSet = new Set(flattenContents)
+    if (flattenContents.length !== flattenContentsSet.size) {
+      throw Error('Graph should not contain duplicate contents keys')
+    }
+    const childrenKeys = Object.keys(object.children)
+    if (flattenContentsSet.size !== childrenKeys.length) {
+      // console.log(flattenContents.filter(c => !childrenKeys.some(k => k === c)))
+      // console.log(childrenKeys.filter(c => !flattenContents.some(k => k === c)))
+      // TODO: update for throw Error when fixed with content
+      console.error(
+        `Inconsistancy in between graph and children: different size (${flattenContentsSet.size} vs ${childrenKeys.length})`,
+      )
+    }
+  },
+})
+
+attrs.graph = {
+  module: graphStructure,
 }
 
 // about to be refactored to define group base on exercise level?
@@ -1654,6 +1926,8 @@ relationAttrs.group = {
     exercise: Literal(1, {
       label: 'Exercise group',
       editable: true,
+      required: true,
+      hidden: true,
       options: arrayOf(100, 1),
       check: value => checkIntegerInBetween(value, 1, 100),
     }),
@@ -1728,6 +2002,7 @@ const sharedPrivateHasStarted = {
 const sharedPublicHasStared = {
   label: 'Starts when',
   type: 'boolean',
+  hidden: true,
   required: true,
   ...Functions({
     'temporal-window has started (in hackathon mode)': getHasStarted,
@@ -2073,11 +2348,9 @@ types.objectRootRelativePath = Literal('../', {
   },
   options: object => {
     if (!object?.parent?.children) return []
-    const sorted = Object.entries(object.parent.children).sort(byValueIdx)
-    const index = sorted.findIndex(([k]) => k === object.key)
-    if (index < 1) return sorted.map(([key, _]) => `../${key}`)
-    const before = sorted.slice(0, index)
-    return before.map(([key, _]) => `../${key}`).reverse()
+    const entries = Object.entries(object.parent.children)
+    const options = entries.filter(([k]) => k !== object.key)
+    return options.map(([key]) => `../${key}`)
   },
 })
 
@@ -2092,7 +2365,10 @@ types.sharedObjectList = {
   },
 }
 
-const sharedRequirements = { editable: true, label: 'Access conditions' }
+const sharedRequirements = {
+  editable: true,
+  label: 'Access conditions',
+}
 
 const contentRequirements = {
   ...sharedRequirements,
@@ -2100,16 +2376,15 @@ const contentRequirements = {
   description:
     'Sets the requirements that have to be met for a content to be accessible to a student.',
   check: (requirements, object) => {
-    const { skills, objects, core, ...rest } = requirements
+    const { skills, objects, ...rest } = requirements
     if (Object.keys(rest).length) {
       throw Error(`Unsupported attribute "${Object.keys(rest)[0]}"`)
     }
-    if (!skills && !objects && !core) {
+    if (!skills && !objects) {
       throw Error('Empty requirements, should be removed')
     }
 
-    const allObjects = [...(objects || []), core || []].flat()
-    const invalidObjectsRequirements = allObjects.filter(path => {
+    const invalidObjectsRequirements = (objects || []).flat().filter(path => {
       const objectFromPath = getObjectFromRelativePath(path, object, {
         throwError: false,
       })
@@ -2508,11 +2783,6 @@ const sharedContentRequirementsForMainAttr = TypeObject({
   ...contentRequirements,
   type: {
     skills: { ...skillsList, instruction: 'Expertises required' },
-    core: {
-      ...types.objectRootRelativePath,
-      label: 'Core content',
-      instruction: 'Relative path of the core content to be succeeded',
-    },
     objects: {
       ...types.sharedObjectList,
       value: (...args) => {
@@ -2972,16 +3242,11 @@ const isPathStatusSucceeded = (path, object) => {
  */
 const hasSucceededRequiredObjects = (requirements, object) => {
   if (!requirements) return true
-  // TODO: in the near future remove the core attribute
-  const { core, objects } = requirements
-  if ((!objects || !objects.length) && !core) return true
+  const { objects } = requirements
+  if (!objects || !objects.length) return true
 
-  // aggregate core object and regular required objects in the list of objects to check
-  // only keep values that are not undefined
   // required objects are the ones that need to be done to unblock the current object
-  const requiredObjects = [...(objects || []), core].filter(
-    p => !Array.isArray(p) && Boolean(p),
-  )
+  const requiredObjects = objects.filter(p => !Array.isArray(p) && Boolean(p))
   // pathway objects represent the choices a student can take to unblock the current object
   // note: at least one object from each pathway must be successfully completed
   const pathWayObjects = objects?.filter(p => Array.isArray(p) && Boolean(p))
@@ -3002,7 +3267,7 @@ const hasSucceededRequiredObjects = (requirements, object) => {
 }
 
 // check if the requirements are met for a given object
-const meetsRequirements = ({ requirements, object, user, progress }) => {
+export const meetsRequirements = ({ requirements, object, user, progress }) => {
   // check if there's already a progress, to not block students who began the project before implementing the requirements feature
   if ((progress && Object.keys(progress).length) || !requirements) return true
   // check if the required skills have been earned & the required objects have been succeeded
@@ -3231,6 +3496,7 @@ types.meetRequirements = Literal(false, {
   label: 'User meet requirement',
   restrictive: true,
   required: true,
+  hidden: true,
   ...Functions({ 'by requirements': getMeetsRequirements }),
 })
 relationAttrs.meetsRequirements = {

package/attrs.js

@@ -14,7 +14,7 @@ const typeCheckers = {
 
 const determinType = value => {
   if (Array.isArray(value)) return 'array'
-  if (typeof value === 'object' && value !== null) return value.type
+  if (typeof value === 'object' && value !== null) return value.type || 'object'
   return typeof value
 }
 const typeChecker = (defs, value, object, key) => {
@@ -309,16 +309,24 @@ const expandAttr = (key, value, defs, object, getUser) => {
       let def
       if (types) {
         const isObject = typeof value[key][i] === 'object'
+
+        // when type is set to "object" for items that cannot be defined in attrs because
+        // the key cannot be known (like types.graphArcContentWithSubContents)
+        const typeCouldNotBeDefined = isObject && Boolean(types.object)
+
         const invalidType =
           !value[key][i].type || typeof value[key][i].type !== 'string'
         const allowedTypes = Object.keys(types).join(',').slice(0, -1)
-        if (isObject && invalidType) {
+
+        if (isObject && invalidType && !typeCouldNotBeDefined) {
           console.warn(
             `Type not allowed. Object item for ${key} array (#${i} item) must have one of these "type" property: ${allowedTypes}.`,
           )
         }
+
         def = isObject ? types[value[key][i].type] : types[typeof value[key][i]]
-        if (!def) {
+
+        if (!def && !typeCouldNotBeDefined) {
           console.warn(
             `Missing type definition. Object item for ${key} array (#${i} item) must have one of these "type" property: ${allowedTypes}.`,
           )

package/graph.js

@@ -0,0 +1,96 @@
+const isCoreObj = (contentShape, coreKey) =>
+  typeof contentShape === 'object' && Object.keys(contentShape)[0] === coreKey
+const isSatteliteObj = (contentShape, satteliteKey) =>
+  typeof contentShape === 'object' &&
+  Object.values(contentShape)[0].some(sat => sat === satteliteKey)
+
+export const getCoreSattelites = (coreObject, objectsList) => {
+  const { key, parent } = coreObject
+  const objects = objectsList || Object.values(parent.children)
+  const sattelitesSection = parent.attrs.graph.innerCircle.find(
+    s => s.type === 'slice' && s.innerArc.contents.find(c => isCoreObj(c, key)),
+  )
+  if (!sattelitesSection) return []
+  const sattelitesObject = sattelitesSection.innerArc.contents.find(c =>
+    isCoreObj(c, key),
+  )
+  const sattelitesList = new Set(...Object.values(sattelitesObject))
+
+  return objects.filter(o => sattelitesList.has(o.key))
+}
+
+export const getCoreOfSattelite = (satteliteObject, objectsList) => {
+  const { key, parent } = satteliteObject
+  const objects = objectsList || Object.values(parent.children)
+  const sattelitesSection = parent.attrs.graph?.innerCircle?.find(
+    s =>
+      s.type === 'slice' &&
+      s.innerArc?.contents.find(c => isSatteliteObj(c, key)),
+  )
+  if (!sattelitesSection) return undefined
+  const coreObject = sattelitesSection.innerArc.contents.find(c =>
+    isSatteliteObj(c, key),
+  )
+
+  return objects.filter(o => o.key === Object.keys(coreObject)[0])
+}
+
+export const flatGraphContents = graph => [
+  ...(graph.centralPoint ? [graph.centralPoint] : []),
+  ...(graph.innerCircle || []).flatMap(section =>
+    section.type === 'slice'
+      ? [
+          ...(section.entryPoint ? [section.entryPoint] : []),
+          ...(section.innerArc?.contents || []).flatMap(c =>
+            typeof c === 'string' ? c : Object.entries(c)[0].flat(),
+          ),
+          ...(section.outerArcs || []).flatMap(arc => arc.contents || []),
+        ]
+      : section.contents,
+  ),
+  ...(graph.middleCircle || []).flatMap(arc => arc.contents || []),
+  ...(graph.outerCircle || []).flatMap(arc => arc.contents || []),
+]
+
+// WARNING: without central point (for linear graph, already destructured)
+export const flatAtomeAndCoreContents = graph => [
+  ...(graph.innerCircle || []).flatMap(section =>
+    section.type === 'slice'
+      ? [
+          ...(section.entryPoint ? [section.entryPoint] : []),
+          ...(section.innerArc?.contents || []).flatMap(c =>
+            typeof c === 'string' ? c : Object.keys(c)[0],
+          ),
+          ...(section.outerArcs || []).flatMap(arc => arc.contents || []),
+        ]
+      : section.contents,
+  ),
+  ...(graph.middleCircle || []).flatMap(arc => arc.contents || []),
+  ...(graph.outerCircle || []).flatMap(arc => arc.contents || []),
+]
+
+export const limitations = {
+  LINE: {
+    maxLinesCount: 6,
+    maxContentsCount: 7, // 7 contents max split along a single line
+  },
+  SLICE: {
+    maxSlicesCount: 4,
+    innerCircle: {
+      maxSubContentsCount: 5, // 5 sub-contents max by content
+      maxContentsCount: 30, // 30 contents max spread evenly over the number of inner cirlces of slices
+    },
+    outerArc: {
+      maxArcsCount: 2,
+      maxContentsCount: 10, // 10 contents max spread evenly over the 1 or 2 outer arcs
+    },
+  },
+  MIDDLE_CIRCLE: {
+    maxArcsCount: 8,
+    maxContentsCount: 70, // 70 contents max spread evenly over the number of arcs
+  },
+  OUTER_CIRCLE: {
+    maxArcsCount: 9,
+    maxContentsCount: 90, // 90 contents max spread evenly over the number of arcs
+  },
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@01-edu/shared",
-  "version": "1.0.12",
+  "version": "1.1.1",
   "type": "module",
   "description": "",
   "scripts": {
@@ -13,6 +13,7 @@
     "./onboarding.js",
     "./attrs.js",
     "./attrs-defs.js",
+    "./graph.js",
     "./languages.js",
     "./definitions-checker.js",
     "./path.js",