[TICKET-PR] DEV.resources: Setup shared @build-in-blocks Typescript code development library

README.md

@@ -1,11 +1,71 @@
 # @build-in-blocks/dev.resources
 
+[![All Contributors](https://img.shields.io/github/all-contributors/build-in-blocks/dev.resources?color=ee8449&style=flat-square)](#contributors)
+
+[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/build-in-blocks/dev.resources/blob/develop/docs.contributors/README.md) [![License: AGPL v3.0](https://img.shields.io/badge/license-AGPL%20v3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) ![build passing](https://img.shields.io/badge/build-passing-brightgreen?style=flat)
+
+#
+
+**Built with:** Node.js v24.0.2
+
+#
+
+**Supported Node.js versions:** Node.js v20.x, v22.x, v24.x and v25.x - Monitored by central Blocks CI from [@build-in-blocks/dev.setup](https://www.npmjs.com/package/@build-in-blocks/dev.setup)
+
+#
+
+**Overview:** Shared `@build-in-blocks` framework Typescript code development library.
+
+#
+
+**Description:** Code used by more than one libraries from the `@build-in-blocks` framework so far, are gathered and developed in this library.
+
+#
+
+**Dependency:** `@build-in-blocks` framework libraries that have `dev.` in their name are only useful for local development, and should only be installed as a `devDependency` in your project.
+
+#
+
+**User guide:** See [docs.users README.md](https://github.com/build-in-blocks/dev.resources/blob/develop/docs.users/README.md)
+
+#
+
+**Contributor guide:** See [docs.contributors README.md](https://github.com/build-in-blocks/dev.resources/blob/develop/docs.contributors/README.md)
+
+#
+
+**Run into any issues?** Report them via our [product issue reports repo](https://github.com/build-in-blocks/product-issue-reports/issues)
+
+#
+
+### Quick installation & usage guide
+
+#### 1. Main package installation
+
+Install the package as a `devDependency` in your project:
+
+````
+npm install -D @build-in-blocks/dev.resources
+````
+
+#### 2. Import needed resources
+
+Import and use what you need from the library in your `.ts` or `.js` file, for example:
+
+````
+import { _default } from '@build-in-blocks/dev.resources';
+
+console.log(_default);
+````
+
+> [!NOTE]  
+> Visit the user guide 👆🏽 to see the full list of variables and functions available.
 
 #
 
 ### Contributors
 
-[![All Contributors](https://img.shields.io/github/all-contributors/build-in-blocks/dev.resources?color=ee8449&style=flat-square)](#contributors) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/build-in-blocks/dev.resources/blob/develop/docs.contributors/README.md) [![License: AGPL v3.0](https://img.shields.io/badge/License-AGPL%20v3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+Thanks to these amazing contributors to the **@build-in-blocks/dev.resources** project. This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. See [emoji key](https://allcontributors.org/docs/en/emoji-key). Contributions of any kind welcome!
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
 <!-- prettier-ignore-start -->

docs.contributors/README.md

@@ -0,0 +1,88 @@
+
+# Contributor guide: Installation instructions for code contributors
+
+Code contributors to **@build-in-blocks/dev.resources** repository should use this document as a reference guide, to setup this library locally during development.
+
+#
+
+### Community Code of Conduct
+
+Read our code of conduct before you start contributing: https://resources.collabocate.community/contribute/code-of-conduct
+
+#
+
+### Prerequisites
+
+Regardless of work experience level, interested code contributors must first complete the [Git & GitHub Workflow Series by **@collabocate-osc**](https://github.com/orgs/collabocate-osc/discussions?discussions_q=is%3Aopen+label%3A%22topic%3A+git+%26+github+collab%22), before making an attempt to work on issue tickets from **@build-in-blocks** repositories and project board.
+
+
+#
+
+### Project board
+
+Find issue tickets to work on through our project board: https://github.com/orgs/build-in-blocks/projects/2
+
+#
+
+### Library compatiblity
+
+Compatible `Node.js` version(s) have been specified in the [root README.md](https://github.com/build-in-blocks/dev.resources) of this repository.
+
+#
+
+### Local development instructions
+
+#### Fork and clone this repo
+
+Follow the instructions to fork and clone this repository locally unto your computer from here: https://github.com/build-in-blocks/.github/wiki/Repo-Contributor-Guide-Extension
+
+#### Install dependencies and run project locally
+
+- **Folder structure:** On your computer, create a new parent folder or go to an existing folder that you will like to be the parent, for both this library and your web or nodejs app. Make sure your cloned `dev.resources` repo folder and your web or nodejs app are inside the parent folder, so that the structure looks like this:
+
+    ````
+    PARENT-FOLDER/
+    ├── dev.resources/
+    └── your-web-or-nodejs-app/
+    ````
+
+- **For library:** Open a terminal specifically for the library, cd into the root of the library folder and run the following script commands.
+
+    Install dependencies:
+
+    ```
+    npm install
+    ```
+
+    Link library:
+
+    ```
+    npm link
+    ```
+    Run the build command to generate or update the `build` folder (after making changes to the `src` folder content):
+
+    ```
+    npm run blocks:ts:build
+    ```
+
+- **For your web or nodejs app:** Open a terminal specifically for your web or nodejs app, cd into the root of your web or nodejs app.
+    - **Step 1:** First install the npm dependencies in your web or nodejs app.
+    - **Step 2:** Add this to your web or nodejs app's package.json dependencies (take note incase library version changes in the future: use the exact version number in the `@build-in-blocks/dev.resources` library's `package.json`. At the time of writing, it is 1.0.0):
+
+        ```
+        "@build-in-blocks/dev.resources": "1.0.0"
+        ```
+
+        Link your app to the library:
+
+        ```
+        npm link ../dev.resources
+        ```
+
+    - **Step 3:** Follow the usage instructions in the [root README.md](https://github.com/build-in-blocks/dev.resources), not from the beginning though; start from the **2. Import needed resources** section (and continue till the end).
+
+#
+
+### Contributors
+
+List of awesome people who contributed to this project can be found in the [root README.md](https://github.com/build-in-blocks/dev.resources). 

docs.release/README.md

@@ -0,0 +1,31 @@
+
+# Release guide: For maintainers in charge of publishing the package
+
+> [!NOTE]  
+> Before releasing/publishing a newer version of this package, do the following so that users and contributors are not affected negatively. Once the requirements below are satisfied, you can publish to the npm registry 🎉
+
+#
+
+> [!NOTE]  
+> Some or all of the processes below will be automated later. For now, ensure to "triple check" these before release.
+
+#
+
+#### This library
+- This library requires you to build/generate a new bundle for consumption - Don't forget to run the `build` script command before publishing.
+
+#
+
+#### Build in blocks libraries in general
+
+- **Update contributors list:** Check to see that all contributors who contributed to the success of the new release have been added to the **contributors list** on the **root README**.
+
+- **Ensure related-code works:** Check that all features to be released in the new version are working as expected, and are complete as shown on our project board.
+
+- **Confirm package.json & docs content:** Always confirm that the content of the `package.json` (`scripts`, the `keywords` array etc.), as well as the **root README**, **user docs**, **contributor docs** and **release docs** content are in good/acceptable shape for the release.
+
+- **Version bumping:** Pending the time when we will automate the version bumping process, always remember to update the version number to a new one in the `package.json` file.
+
+- **Regenerate lock file:** Changes made to the `package.json` should be made to reflect in the lock file. Delete the `package-lock.json` file and the `node_modules` folder, then run `npm i` to generate a new `package-lock.json` file.
+
+- **Pull updated develop branch & create tag:** Double check that you have pulled all the latest changes to your **local** `develop` branch. Create a new tag for the release, via the release page: https://github.com/build-in-blocks/dev.setup/releases.

docs.users/README.md

@@ -0,0 +1,155 @@
+
+# User guide: Package installation, setup and usage
+
+**@build-in-blocks/dev.resources** package contains preconfigured `webpack` setup for both development and production environment. After installation in your web project (and with very minimal intervention on your end), you just need to run `npm run dev` to generate a development mode bundle or `npm run build` to generate a well optimized production mode bundle.
+
+#
+
+### User installation instructions
+
+User installation and setup instructions can in the [root README.md](https://github.com/build-in-blocks/dev.resources).
+
+#
+
+### Technical documentation
+
+- **`BlocksConfig` (Interface)**
+
+    The `BlocksConfig` interface defines the structure for a app's **@build-in-blocks** configuration object. It also allows developers to override default build behaviors, specifically for development environments.
+
+    **Definition**
+
+    ````
+    export interface BlocksConfig {
+        devBuild?: {
+            srcFolderRoot?: string;
+            entryFileName?: string;
+        };
+    }
+    ````
+
+    **Properties**
+
+    |Property | Type| Required| Description|
+    |:-- |:-- |:-- |:-- |
+    |`devBuild` |`object` |No |A nested object containing settings specific to the development build process. |
+    |`devBuild.srcFolderRoot` |`string` |No |The path to the source directory. Overrides the default `'src'`. |
+    |`devBuild.entryFileName` |`string` |No | The name of the main entry file (without extension). Overrides the default `'index'`.|
+
+    **Usage Example**
+
+    **1. Defining a Custom Configuration**
+
+    You can use the interface to type-check your configuration objects:
+
+    ````
+    import { BlocksConfig } from '@build-in-blocks/dev.resources';
+
+    const myConfig: BlocksConfig = {
+        devBuild: {
+            srcFolderRoot: 'app',
+            entryFileName: 'main'
+        }
+    };
+    ````
+
+    **2. Implementing default fallback**
+
+    See `_default` docs below for how you can implement fallback to default blocks config values.
+
+    #
+
+- **`_default` (Configuration Object)**
+
+    The `_default` object defines the fallback project structure and naming conventions for the **@build-in-blocks** framework. It is primarily used when explicit overrides are not provided by the user.
+
+    **Properties**
+
+    |Property | Type| Default| Description|
+    |:-- |:-- |:-- |:-- |
+    |`srcFolderRoot` |`string` |`'src'` |The name of the directory where source files are located. |
+    |`entryFileName` |`string` |`'index'` |The base name of the main entry point file. |
+    |`fileExtension` |`string` |`'.ts'` |The default file extension for the project (includes the leading dot). |
+
+    **Usage Example**
+
+    **1. Construct paths dynamically**
+
+    You can use this object to construct paths dynamically while maintaining consistency with **@build-in-blocks** framework's expectations:
+
+    ````
+    import { _default } from '@build-in-blocks/dev.resources';
+
+    /**
+    * Example: Constructing the default entry path
+    * Result: "src/index.ts"
+    */
+
+    const defaultEntryPoint = `${_default.srcFolderRoot}/${_default.entryFileName}${_default.fileExtension}`;
+
+    console.log(`Looking for entry file at: ${defaultEntryPoint}`);
+    ````
+
+    **2. Implementing default fallback**
+
+    Combine the usage example from `BlocksConfig` (Interface) docs with the code below:
+
+    ````
+    import { _default } from '@build-in-blocks/dev.resources';
+
+    const root = myConfig.devBuild?.srcFolderRoot || _default.srcFolderRoot;
+    console.log(`Starting build from: ${root}`);
+    ````
+
+    #
+
+- **`getCurrentFolderContent`**
+
+    Reads the contents of a specified directory synchronously. This function is a wrapper around Node’s `fs.readdirSync`, designed to handle errors through a provided callback function rather than throwing them directly.
+
+    **Syntax**
+
+    ````
+    getCurrentFolderContent({ workingDirectory, errorFunc });
+    ````
+
+    **Parameters**
+
+    The function accepts a single configuration object with the following properties:
+
+    |Property | Type| Required| Description|
+    |:-- |:-- |:-- |:-- |
+    |`workingDirectory` |`string` |Yes | The absolute or relative path to the directory you want to read.|
+    |`errorFunc` |`Function` |Yes |A callback triggered if the directory cannot be read (e.g., path not found, permission denied). |
+
+    **The `errorFunc` Object:**
+
+    The callback receives an object containing:
+
+    - `error`: An `Error` object (if the error is an instance of `Error`) or `undefined`.
+
+    **Return Value**
+
+    - **Success:** Returns an array of strings (`string[]`), representing the names of the files and folders within the directory (excluding `.` and `..`).
+
+    - **Failure:** Returns `undefined` after executing the `errorFunc` callback.
+
+    **Usage Example**
+
+    ````
+    import { getCurrentFolderContent } from '@build-in-blocks/dev.resources';
+
+    const folderContent = getCurrentFolderContent({
+        workingDirectory: './src/components',
+        errorFunc: ({ error }) => {
+            console.error('Failed to access directory:', error?.message);
+            // Handle your UI updates or logging here
+        },
+    });
+
+    if (folderContent) {
+        console.log('Directory contents:', folderContent);
+    }
+    ````
+
+    #