Noteworthy Puppy Movies

    @woodwing/studio-component-set-tools
    TypeScript icon, indicating that this package has built-in type declarations

    1.21.0 • Public • Published

    studio-component-set-tools

    Tools module for Studio Digital Editor component sets.

    Upgrade notice

    This module is a continuation of the csde-components-validator module. When upgrading to this module there is a slight change: imports from ./lib/index or @woodwing/csde-components-validator/dist/lib/index have to be changed to ./lib/validate or @woodwing/studio-component-set-tools/dist/lib/validate.

    Usage

    The module provides tooling to develop component sets. For example, it contains public API methods to validate a component set.

    validateFolder

    Validates a component set given an input folder.

    import { validateFolder } from './lib/validate';
    
    const validationResult: boolean = await validateFolder('path/to/component-set');

    The validation result is returned as a boolean value and any error is logged to the console.

    validate

    Lower level method that validates the component set given a set of normalized relative paths, a function to get the file content given the normalized relative path and a function that logs errors. This api is useful when the component set is validated in memory.

    import { validate } from './lib/validate';
    
    const filePaths = new Set(['path1', 'path2']);
    const getFileContent = async (normalizedRelativefilePath: string) => 'fileContent';
    const errorReporter = (errorMessage: string) => console.error(errorMessage);
    
    const validationResult: boolean = await validate(filePaths, getFileContent, errorReporter);

    validatePackageSize

    Specific validation of the total maximum size of the component set (in bytes). This method can optionally be used as a quick fail-fast validation before running validate or validateFolder, which both run a full validation on the component set.

    import { validatePackageSize } from './lib/validate';
    
    const packageSize = (await fs.promises.stat('path/to/component-set.zip')).size;
    const errorReporter = (errorMessage: string) => console.error(errorMessage);
    
    const validationResult: boolean = await validatePackageSize(packageSize, errorReporter);

    parseDefinition

    An example of possible usage:

    import { parseDefinition } from '@woodwing/studio-component-set-tools/dist/parser';
    
    const componentsDefinition = getComponentsDefinitionJson();
    // componentSet is a parsed definition
    const componentSet = await parseDefinition(componentsDefinition);

    generateComponentSetInfo

    The generateComponentSetInfo function can be used to generate a plain overview of components and component fields. This information is useful to interpret digital articles created for the given component set. The input for the function is information from the component set: component set definition and rendition files (html, psv, etc).

    The first parameter allows for specifying the components definition. As second parameter, a function is expected that returns the contents of a given component set rendition file as string.

    An example of possible usage:

    import { generateComponentSetInfo } from '@woodwing/studio-component-set-tools/dist/utils';
    
    // The contents of components-definition.json as Javascript object
    const componentsDefinition = getComponentsDefinitionJson();
    
    const info = await generateComponentSetInfo(componentsDefinition, async (relativePath: string) => {
        return (await fs.promises.readFile(relativePath)).toString();
    });

    The returned data contains the field information per component. An example of the returned data:

    {
        components: {
            body: {
                fields: [
                    {
                        contentKey: 'text',
                        type: 'editable',
                    },
                ],
                properties: [
                    {
                        name: 'position',
                        dataType: 'styles',
                    },
                    {
                        name: 'line-height',
                        dataType: 'inlineStyles',
                    },
                ]
            },
            container: {
                fields: [
                    {
                        contentKey: 'main',
                        restrictChildren: ['body'],
                        type: 'container',
                    },
                ],
                properties: [],
            },
        },
    }

    Development

    Watched build/test

    To watch the build:

    npm run watch

    To watch the tests:

    npm run watchtest

    Format

    Formats all code according to Prettier configuration. Linting checks whether all code has been prettified. Formatting can also be applied automatically your favorite IDE or pre-commit hook. Check out the Prettier website for instructions.

    npm run format:write

    Check

    Runs ESLint, Prettier and all unit tests.

    npm run check

    Also available as individual commands

    npm run lint
    npm run format:check
    npm run test

    Releasing a new schema version

    By default the next schema version is being developed under the -next tag. For example, if the latest release version is 1.6.0 you will see there is already a 1.7.0 version in this repository. It can be used by setting the version to 1.7.0-next. This allows developers to already publish new versions of the studio component set tools without having to release a new schema version.

    Using these versions as an example, when the new schema is ready follow these steps:

    1. Duplicate lib/components-schema-v1_7_x.ts as lib/components-schema-v1_8_x.ts.
    2. In lib/validate.ts/getValidationSchemaSource introduce a new matcher on 1.8.0-next for the next in development schema.
    3. Remove the prerelease tag -next from 1.7.0-next
    4. Update tests in test/validate.test.ts (include some simple smoke tests to ensure there are no typos in the version matching logic).

    Publish a new version

    In case you have never published a npm module before, make sure to read the official npm documentation about publishing npm packages.

    Through the Github actions pipeline

    1. Create a branch

    2. Update the version number of this package. For example, to increase the patch version:

      npm version patch -m "Bump validator version to %s"

      Minor version:

      npm version minor -m "Bump validator version to %s"

      This will create a commit and tag for the version as well.

    3. Push and create a PR from the branch.

    4. After review, merge and delete the branch

    5. Create a release in the Release tab of the project. Use the same version as used in the first step for both Tag version and Release title.

    6. Describe the changes in the release

    7. Publish the release

    When the release workflow action succeeds, the new version will be available on npm

    Manually

    Before publishing update the version number of this package. For example, to increase the patch version:

    npm version patch -m "Bump validator version to %s"

    This will create a commit and tag for the version as well.

    Next verify you are logged in as a user with access to the Woodwing organization:

    npm whoami

    Finally publish the scoped package by running:

    npm run check
    npm run build
    npm publish --access public

    Keywords

    none

    Install

    npm i @woodwing/studio-component-set-tools

    DownloadsWeekly Downloads

    149

    Version

    1.21.0

    License

    Apache-2.0

    Unpacked Size

    1.73 MB

    Total Files

    251

    Last publish

    Collaborators

    • sno
    • vintik5000
    • jhu
    • bkr-woodwing
    • jaapvb