Improve `useItem` API to accept collection and item IDs instead of full URL

Inizia leggendo gli hook useItem e useCollection esistenti, quindi esamina StacApiProvider e useStacApiContext per capire come viene esposto l'URL di base. Definisci la nuova firma degli ID di collection e item, aggiorna i chiamanti dell'hook, la documentazione, gli esempi e le indicazioni per la migrazione, quindi verifica che la query utilizzi il percorso collection-item costruito.

The current useItem hook requires users to pass the full URL of an item, which is redundant and inconsistent with other hooks in the library:

// Current API
const { item } = useItem('https://stac-catalog.com/collections/sentinel-2/items/abc123');

This design has several issues:

1. Redundancy: The StacApiProvider already knows the base API URL, yet users must construct the full URL themselves
2. Error-prone: Manual URL construction can lead to mistakes (typos, wrong separators, encoding issues)
3. Not portable: Hardcoded URLs make switching between environments (dev/staging/prod) difficult
4. Inconsistent API: useCollection takes just a collectionId, but useItem requires a full URL

Proposed Solution

Refactor useItem to accept collectionId and itemId parameters, then construct the URL internally using the stacApi from context:

// Proposed API
const { item } = useItem('sentinel-2', 'abc123');

// Or with an object for clarity:
const { item } = useItem({ collectionId: 'sentinel-2', itemId: 'abc123' });

This follows the STAC API spec pattern: /collections/{collectionId}/items/{itemId}

Benefits

1. Consistency: Matches the pattern used by useCollection
2. Simplicity: No manual URL construction required
3. Portability: Environment-agnostic (base URL comes from context)
4. Type safety: Parameters are clearly defined
5. Less error-prone: Reduces chance of URL construction mistakes

Implementation Details

The hook would:

1. Accept collectionId and itemId as parameters
2. Get stacApi from useStacApiContext()
3. Construct the URL using stacApi.baseUrl + /collections/${collectionId}/items/${itemId}
4. Use this constructed URL for the query

Breaking Change

⚠️ This is a breaking change that would require a major version bump.

The hook could detect which signature is being used based on the number/type of arguments.

Related

• Consider whether other hooks might benefit from similar improvements
• Update documentation and examples
• Add migration guide if this is a breaking change