systemlink-cli 1.6.3__tar.gz → 1.6.5__tar.gz

{systemlink_cli-1.6.3 → systemlink_cli-1.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: systemlink-cli
-Version: 1.6.3
+Version: 1.6.5
 Summary: SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates.
 License-File: LICENSE
 Author: Fred Visser

{systemlink_cli-1.6.3 → systemlink_cli-1.6.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "systemlink-cli"
-version = "1.6.3"
+version = "1.6.5"
 description = "SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates."
 authors = ["Fred Visser <fred.visser@emerson.com>"]
 packages = [{ include = "slcli" }]

{systemlink_cli-1.6.3 → systemlink_cli-1.6.5}/slcli/_version.py

@@ -1,4 +1,4 @@
 """Version information for slcli."""
 
 # This file is auto-generated. Do not edit manually.
-__version__ = "1.6.3"
+__version__ = "1.6.5"

{systemlink_cli-1.6.3 → systemlink_cli-1.6.5}/slcli/config_click.py

@@ -116,7 +116,9 @@ def _add_profile_impl(
         elif status["auth_valid"] is True:
             click.echo("  API key:  ✓ Authorized")
 
-        if status.get("elasticsearch_available") is False:
+        if status.get("file_query_endpoint") == "query-files":
+            click.echo("  File query: query-files")
+        elif status.get("elasticsearch_available") is False:
             click.echo("  File query: query-files-linq (Elasticsearch unavailable)")
             click.echo(
                 "      'slcli file list' will fall back automatically; 'slcli file query' requires search-files."

{systemlink_cli-1.6.3 → systemlink_cli-1.6.5}/slcli/file_click.py

@@ -1,12 +1,14 @@
 """CLI commands for managing SystemLink files."""
 
 import json
+import re
 import shutil
 import sys
 import threading
 import time
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlencode
 
 import click
 import questionary
@@ -35,37 +37,149 @@ def _get_search_files_url() -> str:
     return f"{_get_file_service_url()}/search-files"
 
 
-def _is_search_files_unavailable(exc: requests_lib.HTTPError) -> bool:
-    """Return whether the search-files endpoint is unavailable."""
+def _get_query_files_url() -> str:
+    """Get the query-files endpoint URL."""
+    return f"{_get_file_service_url()}/query-files"
+
+
+def _is_file_query_endpoint_unavailable(exc: requests_lib.HTTPError) -> bool:
+    """Return whether a file query endpoint is unavailable."""
     return exc.response is not None and exc.response.status_code in (404, 501)
 
 
 def _exit_search_files_required() -> None:
     """Exit with a user-facing message when search-files is unavailable."""
     click.echo(
-        "✗ File query requires the search-files endpoint, but Elasticsearch is not available.",
+        "✗ File query requires search-files syntax, but this server does not support it.",
         err=True,
     )
     click.echo(
-        "  Use 'slcli file list' for automatic fallback to query-files-linq.",
+        "  Use 'slcli file list' for automatic endpoint fallback, or use a simpler filter.",
         err=True,
     )
     sys.exit(ExitCodes.INVALID_INPUT)
 
 
+def _build_query_files_url(take: int, workspace_id: Optional[str]) -> str:
+    """Build the query-files URL with supported query parameters."""
+    params: Dict[str, Any] = {"take": take}
+    if workspace_id:
+        params["workspace"] = workspace_id
+    return f"{_get_query_files_url()}?{urlencode(params)}"
+
+
+def _get_structured_query_take(take: int, has_client_side_filters: bool) -> int:
+    """Return the query-files page size to use for fallback filtering."""
+    if has_client_side_filters:
+        return max(take * 4, 1000)
+    return take
+
+
+def _get_file_extension(file_item: dict) -> str:
+    """Extract the file extension from file metadata without the leading dot."""
+    file_name = _get_file_name(file_item)
+    return Path(file_name).suffix.lstrip(".")
+
+
+def _filter_files_by_name_or_extension(
+    files: List[dict],
+    needle: str,
+    take: int,
+) -> List[dict]:
+    """Filter files by name or extension using case-insensitive contains matching."""
+    needle_lower = needle.lower()
+    extension_needle = needle_lower.lstrip(".")
+    filtered: List[dict] = []
+
+    for file_item in files:
+        file_name = _get_file_name(file_item).lower()
+        file_extension = _get_file_extension(file_item).lower()
+        if needle_lower in file_name or extension_needle in file_extension:
+            filtered.append(file_item)
+            if len(filtered) >= take:
+                break
+
+    return filtered
+
+
+def _build_structured_file_query(
+    workspace_id: Optional[str],
+    name_filter: Optional[str],
+    id_filter: Optional[str],
+) -> Dict[str, Any]:
+    """Build a query-files request body from high-level file filters.
+
+    Args:
+        workspace_id: Optional workspace ID filter (handled in URL)
+        name_filter: Optional file name substring filter
+        id_filter: Optional comma-separated file IDs
+
+    Returns:
+        Structured query-files request body
+    """
+    del workspace_id
+
+    payload: Dict[str, Any] = {}
+
+    if id_filter:
+        ids = [file_id.strip() for file_id in id_filter.split(",") if file_id.strip()]
+        if len(ids) == 1:
+            payload["idQuery"] = {"operation": "EQUAL", "value": ids[0]}
+        elif ids:
+            payload["idsQuery"] = {"operation": "EQUAL", "ids": ids}
+
+    del name_filter
+
+    return payload
+
+
+def _query_files_structured(
+    take: int,
+    workspace_id: Optional[str],
+    name_filter: Optional[str],
+    id_filter: Optional[str],
+) -> Any:
+    """Query files using the SLS query-files endpoint."""
+    has_client_side_filters = bool(name_filter)
+    url = _build_query_files_url(
+        take=_get_structured_query_take(take, has_client_side_filters),
+        workspace_id=workspace_id,
+    )
+    payload = _build_structured_file_query(
+        workspace_id=workspace_id,
+        name_filter=name_filter,
+        id_filter=id_filter,
+    )
+    resp = make_api_request("POST", url, payload=payload, handle_errors=False)
+
+    if not name_filter:
+        return resp
+
+    data = resp.json()
+    filtered = _filter_files_by_name_or_extension(
+        data.get("availableFiles", []),
+        name_filter,
+        take,
+    )
+    return FilteredResponse({"availableFiles": filtered})
+
+
 def _search_files_with_fallback(
     payload: Dict[str, Any],
+    take: int,
     workspace_id: Optional[str],
     name_filter: Optional[str],
     id_filter: Optional[str],
 ) -> Any:
-    """Try search-files endpoint, fall back to query-files-linq if unavailable.
+    """Try search-files, then query-files, then query-files-linq.
 
-    The search-files endpoint requires additional software (DataFinder) to be
-    installed. If it is not available (HTTP 404), we fall back to query-files-linq.
+    The preferred search-files endpoint is available on SLE. On SLS, the file
+    service exposes query-files instead. Older systems may still require the
+    query-files-linq fallback.
 
     Args:
         payload: The search-files request payload
+        take: Maximum number of files to return for fallback endpoints
         workspace_id: Optional workspace ID filter
         name_filter: Optional name filter string
         id_filter: Optional comma-separated file IDs
@@ -78,13 +192,23 @@ def _search_files_with_fallback(
             "POST", _get_search_files_url(), payload=payload, handle_errors=False
         )
     except requests_lib.HTTPError as exc:
-        if _is_search_files_unavailable(exc):
-            return _query_files_linq_fallback(
-                take=payload.get("take", 25),
-                workspace_id=workspace_id,
-                name_filter=name_filter,
-                id_filter=id_filter,
-            )
+        if _is_file_query_endpoint_unavailable(exc):
+            try:
+                return _query_files_structured(
+                    take=take,
+                    workspace_id=workspace_id,
+                    name_filter=name_filter,
+                    id_filter=id_filter,
+                )
+            except requests_lib.HTTPError as structured_exc:
+                if _is_file_query_endpoint_unavailable(structured_exc):
+                    return _query_files_linq_fallback(
+                        take=take,
+                        workspace_id=workspace_id,
+                        name_filter=name_filter,
+                        id_filter=id_filter,
+                    )
+                raise
         raise
 
 
@@ -144,6 +268,152 @@ def _query_files_linq_fallback(
     return resp
 
 
+def _get_file_by_id_via_query_files(file_id: str) -> Optional[dict]:
+    """Get file metadata by ID using the query-files endpoint."""
+    url = _build_query_files_url(take=1, workspace_id=None)
+    payload = {"idQuery": {"operation": "EQUAL", "value": file_id}}
+    resp = make_api_request("POST", url, payload=payload, handle_errors=False)
+    data = resp.json()
+    files = data.get("availableFiles", [])
+    if files:
+        return files[0]
+    return None
+
+
+def _get_file_by_id_via_query_files_linq(file_id: str) -> Optional[dict]:
+    """Get file metadata by ID using the query-files-linq endpoint."""
+    url = f"{_get_file_service_url()}/query-files-linq"
+    payload = {
+        "filter": f'id = "{file_id}"',
+        "take": 1,
+    }
+    resp = make_api_request("POST", url, payload=payload)
+    data = resp.json()
+    files = data.get("availableFiles", [])
+    if files:
+        return files[0]
+    return None
+
+
+def _extract_search_filter_values(expression: str) -> List[str]:
+    """Extract quoted values from a search-files filter clause."""
+    return [value for value in re.findall(r'"([^"]*)"', expression) if value]
+
+
+def _parse_case_insensitive_filter_value(field_name: str, value: str) -> Tuple[str, str]:
+    """Parse a supported name or extension value into a client-side filter."""
+    if field_name == "extension":
+        if value.startswith("*") and value.endswith("*") and len(value) >= 2:
+            return ("contains", value[1:-1].lstrip("."))
+        if "*" in value:
+            raise ValueError(
+                "Only contains wildcards of the form '*value*' are supported on this server."
+            )
+        return ("equal", value.lstrip("."))
+
+    if value.startswith("*") and value.endswith("*") and len(value) >= 2:
+        return ("contains", value[1:-1])
+    if "*" in value:
+        raise ValueError(
+            "Only contains wildcards of the form '*value*' are supported on this server."
+        )
+    return ("equal", value)
+
+
+def _matches_case_insensitive_filter(
+    file_item: dict,
+    field_name: str,
+    operation: str,
+    value: str,
+) -> bool:
+    """Return whether a file matches a parsed case-insensitive client-side filter."""
+    candidate = (
+        _get_file_name(file_item) if field_name == "name" else _get_file_extension(file_item)
+    )
+    candidate_lower = candidate.lower()
+    value_lower = value.lower()
+
+    if operation == "contains":
+        return value_lower in candidate_lower
+    return candidate_lower == value_lower
+
+
+def _apply_case_insensitive_query_filters(
+    files: List[dict],
+    client_filters: List[Tuple[str, str, str]],
+    take: int,
+) -> List[dict]:
+    """Apply parsed name/extension filters to a query-files response."""
+    if not client_filters:
+        return files[:take]
+
+    filtered: List[dict] = []
+    for file_item in files:
+        if all(
+            _matches_case_insensitive_filter(file_item, field_name, operation, value)
+            for field_name, operation, value in client_filters
+        ):
+            filtered.append(file_item)
+            if len(filtered) >= take:
+                break
+
+    return filtered
+
+
+def _convert_search_filter_to_query_files(
+    filter_query: Optional[str],
+    workspace_id: Optional[str],
+) -> Tuple[Dict[str, Any], Optional[str], List[Tuple[str, str, str]]]:
+    """Convert supported search-files expressions to a query-files request body."""
+    payload: Dict[str, Any] = {}
+    resolved_workspace = workspace_id
+    client_filters: List[Tuple[str, str, str]] = []
+
+    if not filter_query:
+        return payload, resolved_workspace, client_filters
+
+    clauses = [part.strip() for part in re.split(r"\s+AND\s+", filter_query, flags=re.IGNORECASE)]
+
+    for clause in clauses:
+        match = re.match(r"^(name|extension|id|workspaceId):\((.+)\)$", clause)
+        if not match:
+            raise ValueError(
+                "Only name, extension, id, and workspaceId filters joined by AND are supported on this server."
+            )
+
+        field_name, expression = match.groups()
+        if re.search(r"\s+OR\s+", expression, flags=re.IGNORECASE):
+            raise ValueError(
+                "Only name, extension, id, and workspaceId filters joined by AND are supported on this server."
+            )
+        values = _extract_search_filter_values(expression)
+        if not values:
+            raise ValueError(f"Could not parse filter clause: {clause}")
+
+        if field_name == "workspaceId":
+            if len(values) != 1:
+                raise ValueError("workspaceId filters must specify exactly one workspace ID.")
+            if resolved_workspace and resolved_workspace != values[0]:
+                raise ValueError("Conflicting workspace filters were provided.")
+            resolved_workspace = values[0]
+            continue
+
+        if field_name == "id":
+            if len(values) == 1:
+                payload["idQuery"] = {"operation": "EQUAL", "value": values[0]}
+            else:
+                payload["idsQuery"] = {"operation": "EQUAL", "ids": values}
+            continue
+
+        if len(values) != 1:
+            raise ValueError(f"{field_name} filters support exactly one value on this server.")
+
+        operation, parsed_value = _parse_case_insensitive_filter_value(field_name, values[0])
+        client_filters.append((field_name, operation, parsed_value))
+
+    return payload, resolved_workspace, client_filters
+
+
 def _format_file_size(size_bytes: Optional[int]) -> str:
     """Format file size in human-readable format.
 
@@ -217,10 +487,7 @@ def _get_file_size(file_item: dict) -> Optional[int]:
 
 
 def _get_file_by_id(file_id: str) -> Optional[dict]:
-    """Get file metadata by ID using query-files-linq endpoint.
-
-    The API doesn't have a GET /files/{id} endpoint, so we use
-    query-files-linq with an ID filter instead.
+    """Get file metadata by ID using the best available query endpoint.
 
     Args:
         file_id: The file ID to look up
@@ -228,17 +495,12 @@ def _get_file_by_id(file_id: str) -> Optional[dict]:
     Returns:
         File metadata dictionary or None if not found
     """
-    url = f"{_get_file_service_url()}/query-files-linq"
-    payload = {
-        "filter": f'id = "{file_id}"',
-        "take": 1,
-    }
-    resp = make_api_request("POST", url, payload=payload)
-    data = resp.json()
-    files = data.get("availableFiles", [])
-    if files:
-        return files[0]
-    return None
+    try:
+        return _get_file_by_id_via_query_files(file_id)
+    except requests_lib.HTTPError as exc:
+        if _is_file_query_endpoint_unavailable(exc):
+            return _get_file_by_id_via_query_files_linq(file_id)
+        raise
 
 
 def register_file_commands(cli: Any) -> None:
@@ -336,6 +598,7 @@ def register_file_commands(cli: Any) -> None:
             # Try search-files, fall back to query-files-linq if unavailable
             resp = _search_files_with_fallback(
                 payload=payload,
+                take=api_take,
                 workspace_id=workspace_id,
                 name_filter=name_filter,
                 id_filter=id_filter,
@@ -687,8 +950,9 @@ def register_file_commands(cli: Any) -> None:
 
         try:
             # Build request body for search-files
+            api_take = take if format_output.lower() == "json" else (take if take != 25 else 1000)
             query_body: Dict[str, Any] = {
-                "take": take if format_output.lower() == "json" else (take if take != 25 else 1000),
+                "take": api_take,
                 "orderByDescending": descending,
             }
 
@@ -714,12 +978,43 @@ def register_file_commands(cli: Any) -> None:
             else:
                 query_body["orderBy"] = "updated"
 
-            resp = make_api_request(
-                "POST",
-                _get_search_files_url(),
-                payload=query_body,
-                handle_errors=False,
-            )
+            resp: Any
+            try:
+                resp = make_api_request(
+                    "POST",
+                    _get_search_files_url(),
+                    payload=query_body,
+                    handle_errors=False,
+                )
+            except requests_lib.HTTPError as exc:
+                if not _is_file_query_endpoint_unavailable(exc):
+                    raise
+
+                structured_query, structured_workspace, client_filters = (
+                    _convert_search_filter_to_query_files(
+                        filter_query=filter_query,
+                        workspace_id=workspace_id,
+                    )
+                )
+                structured_take = _get_structured_query_take(api_take, bool(client_filters))
+                structured_resp = make_api_request(
+                    "POST",
+                    _build_query_files_url(structured_take, structured_workspace),
+                    payload=structured_query,
+                )
+                if client_filters:
+                    structured_data = structured_resp.json()
+                    resp = FilteredResponse(
+                        {
+                            "availableFiles": _apply_case_insensitive_query_filters(
+                                structured_data.get("availableFiles", []),
+                                client_filters,
+                                api_take,
+                            )
+                        }
+                    )
+                else:
+                    resp = structured_resp
 
             def file_formatter(file_item: dict) -> list:
                 name = _get_file_name(file_item)
@@ -742,9 +1037,12 @@ def register_file_commands(cli: Any) -> None:
             )
 
         except requests_lib.HTTPError as exc:
-            if _is_search_files_unavailable(exc):
+            if _is_file_query_endpoint_unavailable(exc):
                 _exit_search_files_required()
             handle_api_error(exc)
+        except ValueError as exc:
+            click.echo(f"✗ {exc}", err=True)
+            sys.exit(ExitCodes.INVALID_INPUT)
         except Exception as exc:
             handle_api_error(exc)
 

{systemlink_cli-1.6.3 → systemlink_cli-1.6.5}/slcli/main.py

@@ -367,7 +367,10 @@ def info(format: str, skip_health: bool) -> None:
 
     file_query_endpoint = platform_info.get("file_query_endpoint")
     if file_query_endpoint:
-        if platform_info.get("elasticsearch_available") is False:
+        if (
+            file_query_endpoint == "query-files-linq"
+            and platform_info.get("elasticsearch_available") is False
+        ):
             file_query_display = f"{file_query_endpoint} (Elasticsearch unavailable)"
         else:
             file_query_display = str(file_query_endpoint)

{systemlink_cli-1.6.3 → systemlink_cli-1.6.5}/slcli/platform.py

@@ -57,6 +57,7 @@ FEATURE_DISPLAY_NAMES: Dict[str, str] = {
 }
 
 FILE_SEARCH_PATH = "/nifile/v1/service-groups/Default/search-files"
+FILE_QUERY_PATH = "/nifile/v1/service-groups/Default/query-files"
 FILE_QUERY_LINQ_PATH = "/nifile/v1/service-groups/Default/query-files-linq"
 
 
@@ -246,6 +247,39 @@ def get_file_query_capability(api_url: str, api_key: str) -> Dict[str, Any]:
             "elasticsearch_available": None,
         }
 
+    try:
+        query_resp = requests.post(
+            f"{api_url}{FILE_QUERY_PATH}",
+            headers=headers,
+            json={},
+            verify=ssl_verify,
+            timeout=10,
+        )
+        if query_resp.status_code in (200, 400):
+            return {
+                "status": "ok",
+                "file_query_endpoint": "query-files",
+                "elasticsearch_available": False,
+            }
+        if query_resp.status_code in (401, 403):
+            return {
+                "status": "unauthorized",
+                "file_query_endpoint": "query-files",
+                "elasticsearch_available": False,
+            }
+        if query_resp.status_code not in (404, 501):
+            return {
+                "status": "error" if query_resp.status_code >= 500 else "not_found",
+                "file_query_endpoint": None,
+                "elasticsearch_available": False,
+            }
+    except requests.RequestException:
+        return {
+            "status": "unreachable",
+            "file_query_endpoint": None,
+            "elasticsearch_available": False,
+        }
+
     try:
         fallback_resp = requests.post(
             f"{api_url}{FILE_QUERY_LINQ_PATH}",

{systemlink_cli-1.6.3 → systemlink_cli-1.6.5}/slcli/skills/systemlink-webapp/SKILL.md

@@ -161,6 +161,9 @@ import { APP_BASE_HREF } from '@angular/common';
 // Most Nimble component modules are exported from the main `@ni/nimble-angular` barrel.
 // Icon modules (e.g. NimbleIconMagnifyingGlassModule) are ONLY in the main barrel —
 // sub-paths like `@ni/nimble-angular/icons/magnifying-glass` do NOT exist.
+// Do NOT add `@ni/nimble-components` or register raw custom elements just to make
+// Angular templates compile. If a Nimble element is unknown, import the missing
+// Angular module from `@ni/nimble-angular` instead.
 import {
   NimbleThemeProviderModule,
   NimbleButtonModule,
@@ -214,8 +217,25 @@ import { MyFeatureComponent } from './my-feature/my-feature.component';
 export class AppModule {}
 ```
 
+When using `@ni/nimble-angular`, prefer the Angular wrappers end-to-end:
+
+- Do **not** add `@ni/nimble-components` as a direct dependency just to register icons or other raw custom elements.
+- Do **not** use `CUSTOM_ELEMENTS_SCHEMA` as a workaround for unknown Nimble elements. In this codebase that is usually a sign that the corresponding Nimble Angular module import is missing, and `CUSTOM_ELEMENTS_SCHEMA` suppresses valuable template checking.
+- If Angular reports an unknown Nimble tag, fix the module imports first.
+
 For Nimble form controls (`nimble-text-field`, `nimble-select`, etc.), bind with Angular forms APIs (`[(ngModel)]`, `[formControl]`, or `formControlName`) and use `(ngModelChange)` for value-change reactions. Avoid native control bindings like `[value]`, `(input)`, or `(change)` on Nimble elements.
 
+For control labels, prefer Nimble's built-in label pattern by slotting text content inside the control instead of pairing the control with a separate HTML `<label>` element for the primary label:
+
+```html
+<nimble-select [(ngModel)]="selectedWorkspace">
+  Workspace
+  <nimble-list-option *ngFor="let ws of workspaces" [value]="ws.id">
+    {{ ws.name }}
+  </nimble-list-option>
+</nimble-select>
+```
+
 **Critical:** Provide `APP_BASE_HREF` via DI and **remove the `<base href="/">` tag from `index.html`**. SystemLink enforces a `base-uri 'self'` CSP directive; the `<base>` element violates it.
 
 ---
@@ -737,6 +757,8 @@ Save the returned webapp ID — you'll need it for every subsequent redeploy.
 | `InputFieldValidationError` on API call | SDK-generated request body has wrong shape | Inspect raw API; the generated type may add or omit a `request: {}` wrapper. Use direct `fetch` with manually constructed body |
 | nimble-dialog does not open | `*ngIf` destroys element before `ViewChild` can resolve | Remove `*ngIf` from the dialog element; use `@ViewChild` + `ElementRef` and call `nativeElement.show()` / `nativeElement.close()` |
 | Icon module import fails | Icon sub-path `@ni/nimble-angular/icons/...` does not exist | Import icon modules from the main `@ni/nimble-angular` barrel only |
+| Angular says a Nimble tag is unknown | Missing `@ni/nimble-angular` module import | Import the missing wrapper module instead of adding `CUSTOM_ELEMENTS_SCHEMA` or registering raw `@ni/nimble-components` elements |
+| Nimble form control label looks detached or duplicated | Used a separate HTML `<label>` for the primary control label | Slot the label text inside `nimble-text-field`, `nimble-select`, and similar controls |
 | Table rows empty despite correct response | `projection` flattens nested objects | Remove `projection` from query body |
 | `TableRecord` type error | Row type missing index signature | Add `[key: string]: FieldValue \| undefined` |
 | Button appearance invalid | Wrong value for `appearance` attr | Use `appearance="block" appearance-variant="accent"` |

{systemlink_cli-1.6.3 → systemlink_cli-1.6.5}/slcli/skills/systemlink-webapp/references/nimble-angular.md

@@ -1,5 +1,13 @@
 # Nimble Angular — Template & Usage Reference
 
+## Wrapper-first rule
+
+When building Angular apps with Nimble, use `@ni/nimble-angular` wrapper modules as the default integration path.
+
+- Import the needed Angular module for each Nimble control instead of registering raw custom elements from `@ni/nimble-components`.
+- Do not add `CUSTOM_ELEMENTS_SCHEMA` just to silence unknown Nimble elements in templates. That usually hides a missing module import and weakens Angular's template validation.
+- If a Nimble icon or control is unknown, first look for the matching module in `@ni/nimble-angular` and import it.
+
 ## nimble-theme-provider
 
 Wrap your entire app. Always place at the root component level.
@@ -176,6 +184,8 @@ import { NimbleTextFieldModule } from "@ni/nimble-angular";
 </nimble-text-field>
 ```
 
+Use the text inside the element as the control's primary label. Do not add a separate HTML `<label>` element for the basic Nimble control label unless you have a specific accessibility or layout need that cannot be expressed with Nimble's built-in labeling pattern.
+
 Import icon modules from the **main `@ni/nimble-angular` barrel** — icon-specific sub-paths do not exist:
 
 ```typescript
@@ -195,6 +205,7 @@ import { NimbleSelectModule, NimbleListOptionModule } from "@ni/nimble-angular";
 ```html
 <!-- Basic -->
 <nimble-select [(ngModel)]="selectedType" (ngModelChange)="onTypeChange()">
+  Type
   <nimble-list-option value="">All types</nimble-list-option>
   <nimble-list-option value="DOUBLE">Double</nimble-list-option>
   <nimble-list-option value="STRING">String</nimble-list-option>
@@ -203,12 +214,15 @@ import { NimbleSelectModule, NimbleListOptionModule } from "@ni/nimble-angular";
 
 <!-- With built-in filter (useful for long lists) -->
 <nimble-select filter-mode="standard" [(ngModel)]="selectedWorkspace">
+  Workspace
   <nimble-list-option *ngFor="let ws of workspaces" [value]="ws.id"
     >{{ ws.name }}</nimble-list-option
   >
 </nimble-select>
 ```
 
+Use the slotted text content as the select label instead of pairing the control with a separate HTML `<label>` for the primary label.
+
 > Use `filter-mode="standard"` to add a built-in text filter to the dropdown — no custom search logic needed for long option lists.
 
 ---