soaring-symbols 0.1.0-alpha.1

package/API.md

@@ -0,0 +1,116 @@
+# Soaring Symbols: API Reference
+
+This document details the functions exported by the `soaring-symbols` package and the data structures they return.
+
+## Functions
+
+### `listAirlines()`
+
+Returns an array of all airline objects.
+
+- **Returns:** `Airline[]`
+
+### `getAirline(identifier)`
+
+Retrieves a single airline object. The `identifier` can be the airline's IATA code, ICAO code, full name, or URL-friendly slug.
+
+- **Argument:** `identifier` (string)
+- **Returns:** `Airline` (see [Airline Data Model](#airline-data-model)) or `undefined` if not found.
+
+```js
+// All of these will find Vietnam Airlines
+const vna = getAirline('VN')
+const vna = getAirline('HVN')
+const vna = getAirline('Vietnam Airlines')
+const vna = getAirline('vietnam-airlines')
+````
+
+### `getAssets(identifier)`
+
+Retrieves an object with relative paths to an airline's assets. Uses the same `identifier` lookup as `getAirline`.
+
+- **Argument:** `identifier` (string)
+- **Returns:** `AssetPaths` (see [Asset Path Model](#asset-path-model)) or `undefined` if not found.
+
+```js
+const assets = getAssets('VN')
+/*
+{
+    "icon": {
+        "color": "assets/vietnam-airlines/icon.svg",
+        "monochrome": null
+    },
+    "logo": {
+        "color": "assets/vietnam-airlines/logo.svg",
+        "monochrome": "assets/vietnam-airlines/logo-mono.svg"
+    }
+}
+*/
+```
+
+## Data Models
+
+### Airline Data Model
+
+The main object returned by `getAirline()` and found in the `listAirlines()` array.
+
+```json
+{
+    "name": "Vietnam Airlines",
+    "iata": "VN",
+    "icao": "HVN",
+    "country": "VN",
+    "flag_carrier": true,
+    "website": "https://www.vietnamairlines.com",
+    "alliance": "SkyTeam",
+    "slug": "vietnam-airlines",
+    "branding": {
+        "primary_color": "#d99e09",
+        "guidelines": "https://www.vietnamairlines.com/~/media/FilesDownload/AboutUs/Corporate-Identity/GSM-2017-Web1.pdf",
+        "assets": {
+            "icon": {
+                "has_mono_file": false,
+                "color_model": "single",
+                "colors": [
+                    "#d99e09"
+                ]
+            },
+            "logo": {
+                "has_mono_file": true,
+                "color_model": "multi",
+                "colors": [
+                    "#d99e09",
+                    "#005e80"
+                ]
+            }
+        }
+    }
+}
+```
+
+### Asset Path Model
+
+The object returned by `getAssets()`. If a monochrome variant (`-mono.svg`) does not exist for an asset, its value will be `null`.
+
+```json
+{
+    "icon": {
+        "color": "assets/vietnam-airlines/icon.svg",
+        "monochrome": null
+    },
+    "logo": {
+        "color": "assets/vietnam-airlines/logo.svg",
+        "monochrome": "assets/vietnam-airlines/logo-mono.svg"
+    }
+}
+```
+
+### Branding & Asset Details
+
+The `branding.assets` object provides metadata about the SVG files, which you can use to determine how to display them.
+
+- `has_mono_file`: (`boolean`) True if a separate `-mono.svg` file exists (e.g., `icon-mono.svg`).
+- `color_model`: (`"single" | "multi"`) `"single"` if only one color was found in the color SVG; `"multi"` if multiple colors were found.
+- `colors`: (`string[]`) An array of hex colors extracted from the color SVG.
+
+**Note:** If `has_mono_file` is `false` but `color_model` is `"single"`, the color SVG uses a single solid color. This means it can be safely treated as a monochrome asset (e.g., by setting the CSS `fill` property).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Anh Thang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# Soaring Symbols
+
+This project aims to create a meticulously curated collection of airline logos and icons entirely in SVG format, serving as a valuable resource for travelers, aviation enthusiasts, and designers.
+
+> [!IMPORTANT]
+> "Soaring Symbols" provides airline logos/icons in SVG for informational and reference purposes only. We do not claim ownership of any trademarks or copyrighted materials. The logos remain the intellectual property of their respective airlines.
+
+## Project Scope
+
+The initial phase will focus on building a core collection of high-quality SVG logos from major airlines. The collection will be expanded progressively to include regional and potentially historical airlines.
+
+The inclusion of monochrome versions will depend on the airline's brand guidelines and the feasibility of converting their original logos to a simple, one-color format.
+
+## Installation
+
+```bash
+# Using npm
+npm install soaring-symbols
+
+# Using yarn
+yarn add soaring-symbols
+
+# Using pnpm
+pnpm add soaring-symbols
+
+# Using bun
+bun add soaring-symbols
+```
+
+## Usage
+
+```js
+import { listAirlines, getAirline, getAssets } from 'soaring-symbols'
+
+// Get a list of all airlines
+const all = listAirlines()
+
+// Get a specific airline's data
+const vna = getAirline('VN') 
+
+/* output example
+{
+    "name": "Vietnam Airlines",
+    "iata": "VN",
+    "icao": "HVN",
+    "country": "VN",
+    "flag_carrier": true,
+    "website": "https://www.vietnamairlines.com",
+    "alliance": "SkyTeam",
+    "branding": {
+        "primary_color": "#d99e09",
+        "guidelines": "https://www.vietnamairlines.com/~/media/FilesDownload/AboutUs/Corporate-Identity/GSM-2017-Web1.pdf",
+        "assets": {
+            "icon": {
+                "has_mono_file": false,
+                "color_model": "single",
+                "colors": [
+                    "#d99e09"
+                ]
+            },
+            "logo": {
+                "has_mono_file": true,
+                "color_model": "multi",
+                "colors": [
+                    "#d99e09",
+                    "#005e80"
+                ]
+            }
+        }
+    },
+    "slug": "vietnam-airlines"
+}
+*/
+
+// Get asset paths for an airline
+const assets = getAssets('VN')
+
+/* output example
+{
+    "icon": {
+        "color": "assets/vietnam-airlines/icon.svg",
+        "monochrome": null
+    },
+    "logo": {
+        "color": "assets/vietnam-airlines/logo.svg",
+        "monochrome": "assets/vietnam-airlines/logo-mono.svg"
+    }
+}
+*/
+```
+
+For a full list of functions and the data structures they return, please see the [API Reference](./API.md).
+
+## Contributing
+
+Contributions are welcome!
+
+Whether through adding new logos, improving existing ones, or suggesting features to enhance usability. Please refer to our [Contribution Guidelines](https://github.com/anhthang/soaring-symbols/blob/main/CONTRIBUTING.md) for detailed instructions on how to contribute effectively.
+
+## License
+
+This repository is licensed under the MIT License — see [LICENSE](./LICENSE) for details.